Submit a token on an existing account
Developer Documents‣Alternative Payments‣Submit a token on an existing account

If you’re using the API product, upon successful completion of your customer’s first payment, we can return a token in the response. This can be used for future Payments, Authorisation or Payout requests in place of the customer’s physical confirmation via the Apple Pay interface. All you need to do is provide the token itself for each subsequent request.  As these transactions are using a saved Apple Pay account it is not necessary to perform the “merchant validation” step.  To receive the token in the response it is necessary to set registered to true in the payment request.  This is the same approach taken for submitting tokens instead of cards.

Please note that the token is only to be used when the merchant is processing a transaction on the customer’s behalf, without the customer being on their site. If the customer is on the site requesting to pay, they should go through the full Apple Pay process.

 

API Examples
Submit payment with a merchant token

POST /acceptor/rest/transactions/{instId}/payment
{
  "transaction": {
    "currency": "GBP",
    "amount": "1000.0",
    "description": "Sample Transaction",
    "merchantRef": "mer_txn_1234556",
    "commerceType": "MOTO",
    "channel": "WEB"
  },
  "paymentMethod": {
    "applepay": {
      "savedAccountToken": "hJzbc9ccR9CHLlita5g5Jg"
    }
  },
  "customer": {
    "merchantRef": "mer_cust_131241413"
  }
}

HTTP/1.1 201
{
  "processing": {
    "authResponse": {
      "statusCode": "00",
      "message": "ACQUIRER OK",
      "authCode": "112233",
      "gatewayReference": "1049167854342314",
      "gatewayCode": "1",
      "gatewayMessage": "ACCEPTED",
      "avsAddressCheck": "FULL_MATCH",
      "avsPostcodeCheck": "FULL_MATCH",
      "cv2Check": "MATCHED",
      "status": "AUTHORISED"
    },
    "route": "PAYON"
  },
  "paymentMethod": {
    "applepay": {
      "savedAccountToken": "hJzbc9ccR9CHLlita5g5Jg",
      "new": false,
      "cardType": "VISA_DEBIT",
      "cardUsageType": "DEBIT",
      "cardScheme": "VISA",
      "maskedPan": "444433******1111"
    },
    "billingAddress": {
      "line1": "matcheddfdfg",
      "line2": "initialCustomer1AddresssLine2dfg",
      "line3": "fsdfsd",
      "line4": "dfgdfgd",
      "city": "initalCustomer1City",
      "region": "initalCustomer1Region",
      "postcode": "AVS111",
      "country": "United Kingdom",
      "countryCode": "GBR"
    },
    "paymentClass": "CARD"
  },
  "transaction": {
    "transactionId": "13685556791",
    "merchantRef": "mer_txn_1234556",
    "status": "SUCCESS",
    "type": "PAYMENT",
    "amount": 1000,
    "consumerSpend": 1000,
    "currency": "GBP",
    "transactionTime": "2014-03-19T10:11:35.962Z",
    "receivedTime": "2014-03-19T10:11:35.962Z",
    "channel": "WEB"
  },
  "outcome": {
    "status": "SUCCESS",
    "reasonCode": "S100",
    "reasonMessage": "Authorised"
  }
}
API Endpoint
endpoint: /acceptor/rest/transactions/{instId}/payment
method: POST
summary: process payment

parameters:

Name
Data Type
Description
instId
string
The installation id

 

request body:
{
browserInfo {
userAgentHeader string
The Customer’s user agent.
}
sessionId string
Your reference for the Customer’s session.
transaction { Mandatory
currency string
Mandatory
The currency of your Customer’s transaction. Use the 3 character ISO-4217 code.
amount float
Mandatory
The amount of your Customer’s transaction.
commerceType string
Mandatory
Possible Values: ECOM, MOTO, CNP
The commerce type for your Customer’s transaction.
channel string
Mandatory
Possible Values: WEB, MOBILE, SMS, RETAIL, MOTO, IVR, OTHER
The sales channel for your Customer’s transaction.
merchantRef string
Your reference for the transaction. Max length: 255. It’s recommended that you keep this unique.
deferred boolean
Indicates if you want the Payment to be Authorised and Captured separately.
recurring boolean
Set this field if you want to start a Continuous Authority relationship from this transaction.
description string
The description of the transaction. Maximum length: 255.
}
locale string
The ISO-639 code for your Customer’s locale.
customer {
id string
Our ID for the Customer where they are already registered with us.
update boolean
Indicates if you want to update the Customer’s details with the transaction.
email string
Email address for the Customer.
merchantRef string
Conditional
Your reference for the Customer. Not required if registered is set to false, mandatory otherwise.
dob string
Date of birth for the Customer.
billingAddress { The address of the Customer.
line1 string
Line 1 of the Customer’s address.
line2 string
Line 2 of the Customer’s address.
line3 string
Line 3 of the Customer’s address.
line4 string
Line 4 of the Customer’s address.
city string
City of the Customer’s address.
region string
Region of the Customer’s address.
postcode string
Post Code of the Customer’s address.
countryCode string
The 3 character ISO-3166-1 code for the Customer’s address country.
}
displayName string
Conditional
The Customer’s name. Not required if registered is set to false, mandatory otherwise.
telephone string
Telephone number for the Customer.
ip string
The Customer’s IP address.
registered boolean
Indicates if we should register your customer; false if you do not wish to register your customer, otherwise set to true, default value is true.
}
financialServices Mandatory for Fin-Services
dateOfBirth string
Mandatory for Fin-Services
The Customer’s date of birth.
surname string
Mandatory for Fin-Services
The Customer’s surname.
accountNumber string
Mandatory for Fin-Services
The loan account number provided by the merchant, to the Customer.
postCode string
Mandatory for Fin-Services
The postal code of the Customer’s billing address.
}
transactionOptions {
do3DSecure boolean
Indicates if the transaction should be processed with 3DS. This will override account configuration for 3DS.
}
paymentMethod { Mandatory
applepay { Mandatory
savedAccountToken { string
Mandatory
Use if you want to use tokenised card details from a previous transaction.
}
billingAddress { The billing address of the Customer. Will be used for AVS checks
line1 string
Line 1 of the Customer’s billing address.
line2 string
Line 2 of the Customer’s billing address.
line3 string
Line 3 of the Customer’s billing address.
line4 string
Line 4 of the Customer’s billing address.
city string
City of the Customer’s billing address.
region string
Region of the Customer’s billing address.
postcode string
Post Code of the Customer’s billing address.
countryCode string
The 3 character ISO-3166-1 code for the Customer’s billing address country.
}
}
}
response:

applepay {

{
clientRedirect { Information about where to send your customer in the case of 3DS or a Callback.
frame string
Possible Values: CONTAINER, TOP
The redirect type when the transaction is set to suspend and redirect to a new URL.
pareq string
Returned when the transaction is suspended for 3DS authorisation.
url string
The URL the Customer should be redirected to.
}
fraudGuard { Information about the Payment.
score float
The score assigned by FraudGuard. Refer to FraudGuard documentation for further details.
geoLocation {
ipCountry {
country string
The three-character ISO code representing the country of origin, determined by the IP address.
ipValues string
Possible Values: PROXY, SATELLITE, EUROPE, APAC
Categorisation of the IP address used.
}
ipCity string
The origin city of the transaction request, determined by the IP address.
ipRegion string
The origin state or province of the transaction request, determined by the IP address.
distanceFromIpToBilling int
The physical distance from the billing address to the location determined from the IP address.
}
channelRisk {
freeEmailProvider boolean
Whether or not the email address provided in the transaction request is hosted by a free provider.
openProxyRisk float
A rating of how likely it is that the transaction request originated from behind an open proxy.
}
recentActivity {
last24Hours {
attemptsViaIp int
How many transaction requests have originated from this IP address in the last 24 hours.
attemptsViaIp int
How many transaction requests have used this card in the last 24 hours.
}
}
identityMorphing {
againstAddress int
Measure of identity morphing against the address.
againstEmail int
Measure of identity morphing against the email address.
againstCard int
Measure of identity morphing against the card details.
againstIp int
Measure of identity morphing against the IP address.
}
}
transaction {
transactionId string
Our ID for the transaction.
deferred boolean
Indicates if the Payment capture is deferred.
merchantRef string
Your reference for the transaction.
merchantDescription string
The description of the transaction provided in the request.
status string
Possible Values: SUCCESS, FAILED, PENDING, EXPIRED, CANCELLED, VOIDED
The current state of the transaction.
type string
Possible Values: PAYMENT, PREAUTH, PAYOUT, REFUND, CAPTURE, CANCEL, REPEAT, CASH_ISSUE, CASH_PAYMENT
Indicates the type of the transaction.
amount float
Indicates the requested amount of the transaction.
consumerSpend float
Indicates the actual amount of the transaction. This will be zero for any type of INITIALIZE transaction, deferred transactions, and rejected transactions.
currency string
Indicates the currency of the transaction. Use the 3 character ISO-4217 code.
transactionTime string
The date and time we processed the transaction in ISO-8601 format.
receivedTime string
The date and time we received the transaction in ISO-8601 format.
commerceType string
Possible Values: ECOM, MOTO, CNP
The Commerce Type of the transaction.
channel string
Possible Values: WEB, MOBILE, SMS, RETAIL, MOTO, IVR, OTHER
The Sales Channel of the transaction.
relatedTransaction { This field is not applicable for Payments. In case of Refunds it indicates the transaction that was refunded.
transactionId string
Our ID for the transaction that was original.
merchantRef string
Your reference for the transaction that was original.
}
}
processing { Information about the authorisation status of your transaction.
route string
The name of the processing engine your transaction was submitted to.
voidSuccessful boolean
Indicates if the transaction was voided by a Post Authorisation callback.
authResponse {
statusCode string
The code for the status received from the authoriser, if applicable.
acquirerReference string
The reference received from the authoriser for your transaction, if applicable.
acquirerName string
Name of the authoriser, if applicable.
message string
The message received from the authoriser, if applicable.
authCode string
The code received from the authoriser, if applicable.
gatewayReference string
The reference received from the processing engine.
gatewaySettlement string
The date the processing engine will settle the transaction. in YYYY-MM-DD format.
gatewayCode string
The code for the status received from the processing engine.
gatewayMessage string
The message received from the processing engine.
avsAddressCheck string
Possible Values: NOT_CHECKED, FULL_MATCH, NOT_MATCHED, NOT_PROVIDED
Results for the Address Verification checks, if applicable, if applicable.
avsPostcodeCheck string
Possible Values: NOT_CHECKED, FULL_MATCH, NOT_MATCHED, NOT_PROVIDED
Results for the PostCode Verification checks, if applicable.
cv2Check string
Possible Values: NOT_CHECKED, MATCHED, NOT_MATCHED
Results for the CV2 Verification checks, if applicable.
gatewayStatus string
The status received from the processing engine.
status string
Possible Values: AUTHORISED, DECLINED, REVERSED, REVERSE_FAILED, ERROR
The status received from the authoriser, if applicable.
}
}
threeDSecure { Information about the 3D Secure status of your transaction.
authenticationStatus string
Possible Values: AUTHENTICATED, ATTEMPTED, FAILED, ERROR
The status of 3DS authentication check.
authenticationIndicator string
Possible Values: Y, A, N, U
The indicator of the 3DS authentication status.
enrolmentDateTime string
The date and time the 3DS enrolment check was performed in ISO-8601 format.
scheme string
The scheme that processed the transaction for 3DS.
eci string
The eCommerce indicator for the transaction.
status string
Possible Values: AUTHENTICATED, BYPASSED, FAILED, NOT_ENROLLED, ENROLMENT_CHECK_FAILURE, INCOMPLETE, NOT_AVAILABLE, NOT_IMPLEMENTED
The overall 3DS result for the transaction.
xid string
The ID used during 3DS processing.
enrolmentIndicator string
Possible Values: Y, N, U
The indicator of the 3DS enrolment status.
enrolmentStatus string
Possible Values: ENROLLED, NOT_ENROLLED, UNABLE_TO_AUTHENTICATE
The status of the 3DS enrolment check.
}
customer { Information about the Customer
id string
Our ID for the Customer.
merchantRef string
Your reference for the Customer.
}
financialServices { Information about the financial services.
dateOfBirth string
The Customer’s date of birth.
surname string
The Customer’s surname.
accountNumber string
The loan account number provided by the merchant, to the Customer.
postCode string
The postal code of the Customer’s billing address.
}
outcome { Information about the overal outcome of the request.
reasonMessage string
A message indicating the overall outcome of the request. This is where we’ll provide detailed reasons for any errors.
status string
Possible Values: SUCCESS, FAILED
The overall outcome of the request.
reasonCode string
A code indicating the overall outcome of the request. Refer to Errors for more information.
}
paymentMethod { Information about the Payment Method used in the request.
applepay {
displayName string
The display name Apple Pay uses for this card (e.g. VISA 1234)
cardType string
information about the type of card used by the Apple Pay transaction
cardUsageType string
The card usage type (credit or debit)
cardScheme string
The card scheme (VISA, Mastercard, Amex, etc) 
savedAccountToken string
The token for the card.
}
paymentClass string
The classification of payment method used. Eg. Card, Cash, PayPal
billingAddress { The billing address of the Customer. Will be used for AVS checks. We’ll save the billing address when the customer makes their first payment. Providing a billing address for subsequent payments will update the address we’ve saved if you send new, empty or no values for each field.
line1 string
Line 1 of the Customer’s billing address.
line2 string
Line 2 of the Customer’s billing address.
line3 string
Line 3 of the Customer’s billing address.
line4 string
Line 4 of the Customer’s billing address.
city string
City of the Customer’s billing address.
region string
Region of the Customer’s billing address.
postcode string
Post Code of the Customer’s billing address.
country string
Country name of the Customer’s billing address.
countryCode string
The 3 character ISO-3166-1 code for the Customer’s billing address country.
}
}
}