New API Version | Last Updated: 30 September 2024 | Change Log |
Take a card on file sale
Use our card on file sale resource when your customer is initiating a payment using stored card details, and you want to instantly trigger the settlement process. Read more about card on file mandates here.
What are card on file payments?
- The customer is actively particpating in making a payment at the point of authorization using card details you have previously stored/ intend to store
- Does not follow a schedule
- Requires explicit permission from the customer to store the card on their account for use in a “one-click” model
- Sometimes referred to as Customer Initiated Transactions (CIT)
migrateCardOnFileSale
request
POST
your card on file sale request to our payments:migrateCardOnFileSale
action link resource received in your query the payments root resource request.
POST
https://try.access.worldpay.com/payments/sales/migrateCardOnFile
The requests below contain all the mandatory fields needed for a successful authorization request.
Click the tabs below to see all the mandatory fields for all supported paymentInstrument
parameters.
migrateCardOnFileSale
request body:
{ "transactionReference": "Memory265-13/08/1876", "merchant": { "entity": "default" }, "instruction": { "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/plain", "cardNumber": "4444333322221111", "cardExpiryDate": { "month": 5, "year": 2035 } } } }
Sale request parameters
Parameter | Required | Description |
---|---|---|
transactionReference | ✅ | A unique reference generated by you. This is used to identify a payment throughout its lifecycle. See transaction reference format for more details and the best practices. |
merchant | ✅ | An object that contains information about the merchant. |
merchant.entity | ✅ | Direct your payment to assist with billing, reporting and reconciliation. This is mandatory for authentication and queries. Contact your Implementation Manager for more details. |
merchant.mcc | ❌ | You can apply a merchant category code (mcc ) to an individual request. You can only provide an mcc if we have enabled the dynamic mcc feature during boarding. If enabled but not provided, merchant.mcc defaults to a configured value. For more information contact your Relationship Manager. |
merchant.paymentFacilitator | ❌ | An object containing Payment Facilitator information. If required you must send:
|
channel | ❌ | The payment channel indicates the interaction of the cardholder with the merchant. Possible value :
moto to process an authorization as a Mail Order or Telephone Order (MOTO) transaction. If channel is not provided, the authorization will be processed as ecommerce by default. Note 3DS authentication data cannot be supplied for MOTO payments. |
instruction | ✅ | An object that contains all the information related to the payment. |
instruction.narrative | ✅ | The text that appears on your customer's statement. Used to identify the merchant. See narrative format for more details and best practices. |
narrative.line1 | ✅ | The first line of the narrative which appears on your customer's statement (24 characters max. If character is not supported, it is replaced with a space.). See narrative line1 format for more details. |
narrative.line2 | ❌ | Additional details about the payment e.g. order number, telephone number. |
instruction.value | ✅ | An object that contains information about the value of the payment. |
value.currency | ✅ | The three digit currency code. See list of supported currencies. |
value.amount | ✅ | The payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50. You can find the relevant exponent in our currency table. |
instruction.paymentInstrument | ✅ | An object that contains the payment type and details. Available paymentInstrument s:
|
paymentInstrument.cardExpiryDate | ✅ | An object that contains your customer's card expiry date. Mandatory for all "type":"card/plain" requests. |
paymentInstrument.cardNumber | ✅ | An object that contains your customer's card number. Mandatory for "type":"card/plain" requests. |
paymentInstrument.cvc | ❌ | CVC is a unique set of 3 or 4 numbers on the back of the card. Our API checks to see if the CVC supplied matches the CVC held by the issuing bank. |
paymentInstrument.cardHolderName | ❌ | An object that contains your customer's card name. This is not a mandatory field however it is recommended that you supply this to improve authorization rates. If not sent, the default is "Not Supplied". |
paymentInstrument.billingAddress | ❌ | An object containing the billing address information. If included you must send at least:
card/plain payment instrument. Our API checks the submitted AVS to see if it matches the address registered with the issuing bank. If the address supplied does not match the registered address it means that the payment carries additional risk. |
scheme.reference | ❌ | Unique reference provided by the schemes that identifies a repeat payment agreement between you and the customer. A new reference is generated for every subsequent payment in the agreement. You can submit this for card/plain and card/token requests. Most but not all issuers return this. Note The token can only store a single scheme reference. Supplying a scheme reference in your token request, overrides the scheme reference stored in the token. |
instruction.intent | ❌ | A parameter detailing the reason for this particular card on file agreement. Possible value:
|
instruction.debtRepayment | ❌ | DRI is a flag which identifies a payment as being for the purpose of repaying a debt. Possible value:
|
customer.riskProfile | ❌ | Used to apply the SCA exemption in the payment request and update the FraudSight data model to benefit future payments. |
3DS
The below table describes the mandatory 3DS authorization request parameters:
3DS data cannot be supplied for MOTO transactions.
|Parameter|Required|Description| |---|---| |customer
|✅|An object containing the result of your customer's verification. For more details see 3DS verification.| |authentication.type
|✅|3DS| |authentication.version
|✅|The version of 3DS used to process the transaction.
For 3DS1 - 1.0.2
For 3DS2 - 2.1.0
or 2.2.0
authentication.eci
|✅|Electronic Commerce Indicator (ECI).Indicates the outcome of the 3DS verification.
- 02 or 05 - Fully Authenticated Transaction
- 01 or 06 - Attempted Authentication Transaction
- 00 or 07 - Non 3-D Secure Transaction
- Mastercard - 02, 01, 00
- Visa - 05, 06, 07
- Amex - 05, 06, 07
- JCB - 05, 06, 07
- Diners - 05, 06, 07
authentication.authenticationValue
|✅|Required, if authentication.eci
value is 01, 02, 05 or 06.A cryptographic value that provides evidence of the outcome of a 3DS verification.
- Visa - Cardholder Authentication Verification Value (CAVV)
- Mastercard - Universal Cardholder Authentication Field (UCAF)
authentication.authenticationValue
must be 28 digits max and must be base64-encoded.| |authentication.transactionId
|✅|Required, if authentication.eci
value is 01, 02, 05 or 06.A unique authentication transaction identifier, generated by the issuer.
For version 3DS1:
transactionId
is base64-encoded and 28 digits in length.For version 3DS2:
transactionId
follows RFC 4122 UUID standard and is 36 characters in length.| |authentication.cryptogramAlgorithm
|❌|Indicates the algorithm used to generate the cryptogram. For Cartes Bancaires authorizations only.| |
authentication.challengePreference
|❌|Indicates the preferred challenge behavior.- noPrefrence
- noChallengeRequested
- challengeRequested
- challengeMandated
For Cartes Bancaires authorizations only.| |
authentication.authenticationFlow
|❌|challenge
- Your customer was redirected to their bank to complete authenticationfrictionless
- Your customer completed authentication without needing to be redirected to their bank
For Cartes Bancaires authorizations only.| |
authentication.statusReason
|❌|Provides further information relating to the outcome of the authentication. Returned for failed authentications only. For Cartes Bancaires authorizations only.| |
authentication.cancellationIndicator
|❌|An indicator as to why the authentication was cancelled. - -
01
- Cardholder selected cancel - -
02
- Reserved for future use - -
03
- Authentication timed out - -
04
&05
- Authentication timed out at ACS provider - -
06
- Transaction error - -
07
- Unknown - -
08
- Transaction timed out at SDK
For Cartes Bancaires authorizations only.| |
authentication.networkScore
|❌|The global score calculated by the Cartes Bancaires scoring platform.For Cartes Bancaires authorizations only.| |
authentication.brand
|❌|The card brand used in the authentication.For Cartes Bancaires authorizations only.|
Optional Parameters
Example request (all parameters)
The requests below contain all the mandatory and optional fields for a migrateCardOnFileSale
request.
Full migrateCardOnFileSale
request body:
{ "transactionReference": "Memory265-13/08/1876", "merchant": { "entity": "default", "mcc": "6432", "paymentFacilitator": { "pfId": "12345", "isoId": "12345", "subMerchant": { "name": "John", "merchantId": "12345", "postalCode": "SW1 1AA", "street": "Regent Street", "city": "London", "state": "WSM", "countryCode": "826", "taxId": "ABC-123456789", "email": "test@email.com", "telephone": "+447987 654321" } } }, "channel": "moto", "instruction": { "narrative": { "line1": "Mind Palace Ltd", "line2": "Memory265-13/08/1876" }, "scheme": { "reference": "28379213" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "billingAddress": { "address1": "221B Baker Street", "address2": "Marylebone", "address3": "Westminster", "postalCode": "NW1 6XE", "city": "London", "state": "Greater London", "countryCode": "GB" }, "type": "card/plain", "cardHolderName": "Sherlock Holmes", "cardNumber": "4444333322221111", "cardExpiryDate": { "month": 12, "year": 2020 } }, "intent": "instalment" }, "customer": { "riskProfile": "https://try.access.worldpay.com/riskProfile/ewogICJ2IiA6IDEsC" } }
migrateCardOnFileSale
response
Access Worldpay returns a WP-CorrelationId
in the headers of service responses. We highly recommend you log this. The WP-CorrelationId
is used by us to examine individual service requests.
Successful response
Access Worldpay returns a WP-CorrelationId
in the headers of service responses. We highly recommend you log this. The WP-CorrelationId
is used by us to examine individual service requests.
You receive:
- an HTTP code
201
- an
"outcome": "Sent for Settlement"
- risk factors (only returned if issuer identifies conflict)
- an exemption result and reason (only if you supplied a risk profile to request an SCA exemption)
- an issuer authorization code
- a scheme reference (supported by major card schemes, but may not be returned for all schemes/regions)
- a
paymentInstrument
- links to refund, partially refund, reverse your request or query your payment.
- an authorization link for the next payment in your repeat payment agreement
paymentInstrument
The "paymentInstrument"
object is returned if we are able to provide information related to the underlying card used in the authorization request.
Note that if the paymentInstrument
object is returned, there is no guarantee that each field listed below will be returned with every transaction.
Parameter | Description |
---|---|
paymentInstrument.type | The type of paymentInstrument. Eg:
|
paymentInstrument.card.brand | The card brand. Sometimes referred to as the network or scheme. Eg:
|
paymentInstrument.card.number.bin | The card bin. Eg:444433 Note this may contain the * character. |
paymentInstrument.card.number.last4Digits | The last four digits of the card. Eg: 1111 Note this may contain the * character, where the card number is less than 16 digits. |
paymentInstrument.card.expiryDate.month | The card expiry month. Eg: 11 |
paymentInstrument.card.expiryDate.year | The card expiry year. Eg: 2025 |
paymentInstrument.card.fundingType | How the card is funded. Eg:
|
paymentInstrument.card.category | Whether the card is classed as a consumer card or a card for commercial use. Eg:
|
paymentInstrument.card.countryCode | The alpha-2 ISO-3166 country code that the card was issued in. May return "N/A" where the country is unknown. Eg: GB |
paymentInstrument.card.issuer.name | The name of the card issuer. Eg: Some Issuer PLC. |
paymentInstrument.card.paymentAccountReference | The payment account reference (PAR) is a non-financial reference that uniquely identifies the underlying cardholder account. This allows you to correlate payments made with differing instruments (e.g. "card/plain" and "card/wallet+applepay" ), where the same account funds the transaction. A PAR cannot be used to intiate a payment. Eg: ABC123DEF456GHI789JKL123MNO45 |
Refused response
You receive:
- an HTTP code
201
- an
"outcome": "refused"
- a refusal code
- a
description
which gives additional context on the refusal - a refusal advice code (only if returned by the card scheme and acquirer)
- risk factors (only returned if issuer identifies conflict)
- an exemption result and reason (only if you supplied a risk profile to request an SCA exemption)
Example response:
{ "outcome": "Sent for Settlement", "riskFactors": [{ "type": "cvc", "risk": "not_matched" }, { "type": "avs", "detail": "address", "risk": "not_checked" }, { "type": "avs", "detail": "postcode", "risk": "not_checked" } ], "issuer": { "authorizationCode": "12345A" }, "scheme": { "reference": "1260019172" }, "exemption": { "result": "honored", "reason": "issuerHonored" }, "paymentInstrument": { "type": "card/plain+masked", "card": { "brand": "visa", "number": { "bin": "444433", "last4Digits": "1111" }, "expiryDate": { "month": 12, "year": 2025 }, "fundingType": "credit", "category": "consumer", "issuer": { "name": "Some Issuer PLC" }, "paymentAccountReference": "ABC123DEF456GHI789JKL123M" } }, "_links": { "payments:refund": { "href": "https://try.access.worldpay.com/payments/settlements/refunds/full/eyJrIjoiazNhYjYzMiJ9" }, "payments:partialRefund": { "href": "https://try.access.worldpay.com/payments/settlements/refunds/partials/eyJrIjoiazNhYjYzMiJ9" }, "payments:reversal": { "href": "https://try.access.worldpay.com/payments/sales/reversals/eyJrIjoiazNhYjYzMiJ9" }, "payments:events": { "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiJ9" }, "curies": [{ "name": "payments", "href": "https://try.access.worldpay.com/rels/payments/{rel}", "templated": true }] } }
In case of an error, you can get further information in our error reference.
riskFactors
To reduce the probability of processing a fraudulent payment, supply your customer's billing address and cvc in your authorization request.
We check this with your customer's issuing bank and include any conflicts in our response.
The riskFactors
array is returned only if there is a risk associated with the authorization request. The riskFactors
array returns an object for avs
, cvc
or riskProfile
only if this information was included in the authorization request and if any risk was identified.
The table below describes the response parameters:
Parameter | Description |
---|---|
riskFactors.type | Returns avs , cvc or riskProfile |
riskFactors.detail | For avs only.Returns postcode or address |
riskFactors.risk | Returns not_checked , not_matched , not_supplied or verificationFailed |
exemption
An exemption result and reason if a risk profile was included in your authorization request.
The table below describes the response parameters:
Parameter | Description |
---|---|
exemption.result | Returns honored , outOfScope , rejected or unknown |
exemption.reason | For honored , returns issuerHonored or unknown .For outOfScope , returns merchantInitiatedTransaction , oneLegOut , moto , contactless or unknown .For rejected , returns issuerRejected , highRisk , invalid , unsupportedScheme , notSubscribed , unsupportedAcquirer or unknown |
Soft decline
The issuer responds with a soft decline (refusal code 65), if no exemption has been applied to the payment. The next logical step for this is to proceed with 3DS authentication.