Last Updated: 23 October 2024 | Change Log

Take a card on file authorization

Use our card on file authorize resource when your customer is initiating a payment using stored card details. Read more about card on file mandates here.

What are card on file payments?

  • The customer is actively participating 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)

On this page:

Card on file authorization with verification

Verify your customer's account before submitting your first card on file payment for authorization.

Card on file request

POST your card on file request to the payments:cardOnFileAuthorize action link received in your successful cardOnFile intelligent or dynamicCardOnFile verification.

Card on file example request

POST https://try.access.worldpay.com/payments/authorizations/cardonFile/{resource}

Note

Click the tabs below to see all the mandatory fields for all supported paymentInstrument parameters.

Card on file request body:

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 5,
                "year": 2035
            }
        }
    }
}

Parameter descriptions

ParameterRequiredDescription
transactionReferenceA unique reference generated by you that is used to identify a payment throughout its lifecycle. See transaction reference format, for more details and the best practices.
merchantAn object that contains information about the merchant.
merchant.entityDirect your payment to assist with billing, reporting and reconciliation. This is mandatory for Authentication and Queries.
Contact your Implementation Manager for more details.
merchant.mccYou 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.paymentFacilitatorAn object containing Payment Facilitator information. If required you must send:
  • pfId
  • isoId
  • subMerchant.merchantId
  • subMerchant.postalcode
  • subMerchant.street
  • subMerchant.city
  • subMerchant.countryCode
  • subMerchant.telephone (mandatory for Amex)
  • subMerchant.email (mandatory for Amex)
This information is required for every card on file request only if you are a Payment Facilitator. You can find more formatting information here.
instructionAn object that contains all the information related to the payment.
instruction.narrativeThe text that appears on your customer's statement. Used to identify the merchant.
See narrative format for more details and the best practices.
narrative.line1The first line of the narrative which appears on your customer's statement (24 character max. If character is not supported it is replaced with a space.).
See narrative line1 format for more details.
narrative.line2Additional details about the payment e.g. order number, telephone number.
instruction.debtRepaymentDRI is a flag which identifies a payment as being for the purpose of repaying a debt. Possible value :
  • true (only supply if true)
For more information contact your Relationship Manager.
instruction.valueAn object that contains information about the value of the payment.
value.currencyThe 3 digit currency code.
See list of supported currencies.
value.amountThe 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.paymentInstrumentAn object that contains the payment type and details.
Available paymentInstruments:
paymentInstrument.cardExpiryDateAn object that contains your customer's card expiry date.
Mandatory for all "type": "card/plain" requests.
paymentInstrument.cardNumberAn object that contains your customer's card number. Mandatory for "type": "card/plain" requests.
paymentInstrument.cvcCVC 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.cardHolderNameAn 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.billingAddressAn object containing the billing address information. If included you must send at least:
  • address1
  • city
  • countryCode
  • postalCode
This is used for Address Verification Service (AVS) and can only be supplied with a card/plain,card/wallet+applepay or card/wallet+googlepay 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.
instruction.intentA parameter detailing the reason for this particular card on file agreement. Possible value: *instalment * subscription
customer.riskProfileUsed to apply the SCA exemption in the payment request and update the FraudSight data model to benefit future payments.

3DS

3DS authorization request parameter descriptions

To get the customer authentication object you must complete an authentication request using our 3DS API.

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 5,
                "year": 2035
            }
        }
    },
    "customer": {
        "authentication": {
            "version": "1.0.2",
            "type": "3DS",
            "eci": "05",
            "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
            "transactionId": "z9UKb06xLziZMOXBEmWSVA1kwG0="
        }
    }
}
Note
  • 3DS1 is supported in certain regions only
  • 3DS data cannot be supplied for MOTO transactions

The descriptions of parameters from your 3DS authorization request

ParameterRequiredDescription
customerAn object containing the result of your customer's verification. For more details see 3DS verification.
authentication.type3DS
authentication.versionThe version of 3DS used to process the transaction.
For 3DS1 - 1.0.2
For 3DS2 - 2.1.0 or 2.2.0
Note
Required for Mastercard's Identity Check transactions in Authorization.
authentication.eciElectronic 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.authenticationValueRequired, 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.transactionIdRequired, 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.cryptogramAlgorithmIndicates the algorithm used to generate the cryptogram.
For Cartes Bancaires authorizations only.
authentication.challengePreferenceIndicates 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 authentication
  • frictionless - Your customer completed authentication without needing to be redirected to their bank

For Cartes Bancaires authorizations only.
authentication.statusReasonProvides further information relating to the outcome of the authentication. Returned for failed authentications only.
For Cartes Bancaires authorizations only.
authentication.cancellationIndicatorAn 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.networkScoreThe global score calculated by the Cartes Bancaires scoring platform.
For Cartes Bancaires authorizations only.
authentication.brandThe card brand used in the authentication.
For Cartes Bancaires authorizations only.

Optional parameters

Example Card on File Authorization request (all parameters)

The requests below contain all the mandatory and optional fields needed for a successful card on file request.

Full card on file request body

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default",
        "mcc": "1234",
        "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"
            }
        }
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd",
            "line2": "Memory265-13/08/1876"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "cvc": "123",
            "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": 5,
                "year": 2035
            }
        },
        "intent": "instalment"
    },
    "customer": {
        "riskProfile": "https://try.access.worldpay.com/riskProfile/ewogICJ2IiA6IDEsC"
    }
}

Card on file response

Best Practice

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 payment

You receive:

  • an HTTP code 201
  • an "outcome": "authorized"
  • 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 cancel, settle, partially settle or query payment events
  • 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

Note that if the paymentInstrument object is returned, there is no guarantee that each field listed below will be returned with every transaction.

ParameterDescription
paymentInstrument.typeThe type of paymentInstrument. Eg:
  • card/plain+masked
  • card/network+masked
  • card/network
paymentInstrument.card.brandThe card brand. Sometimes referred to as the network or scheme. Eg:
  • "visa"
  • "mastercard"
  • "amex"
paymentInstrument.card.number.binThe card bin. Eg:
444433
Note
this may contain the * character.
paymentInstrument.card.number.last4DigitsThe 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.monthThe card expiry month. Eg:
11
paymentInstrument.card.expiryDate.yearThe card expiry year. Eg:
2025
paymentInstrument.card.fundingTypeHow the card is funded. Eg:
  • credit
  • debit
  • prepaid
  • deferredDebit
  • chargeCard
paymentInstrument.card.categoryWhether the card is classed as a consumer card or a card for commercial use. Eg:
  • consumer
  • commercial
paymentInstrument.card.countryCodeThe 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.nameThe name of the card issuer. Eg:
Some Issuer PLC.
paymentInstrument.card.paymentAccountReferenceThe 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 payment

You receive:

  • an HTTP code 201
  • an "outcome": "refused"
  • a refusal code
  • a description which gives additional context on the refusal
  • 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": "authorized",
    "riskFactors": [{
            "risk": "not_matched",
            "type": "cvc"
        },
        {
            "risk": "not_checked",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "not_checked",
            "detail": "address",
            "type": "avs"
        }
    ],
    "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:cancel": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:settle": {
            "href": "https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:partialSettle": {
            "href": "https://try.access.worldpay.com/payments/settlements/partials/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:events": {
            "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:cardOnFileAuthorize": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cardOnFile/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:recurringAuthorize": {
            "href": "https://try.access.worldpay.com/payments/authorizations/recurring/eyJrIjoiazNhYjYzMiJ9"
        },
        "curies": [{
            "name": "payments",
            "href": "https://try.access.worldpay.com/rels/payments/{rel}",
            "templated": true
        }]
    }
}

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:

ParameterDescription
riskFactors.typeReturns avs, cvc or riskProfile
riskFactors.detailFor avs only.
Returns postcode or address
riskFactors.riskReturns not_checked, not_matched, not_supplied or verificationFailed

exemptions

An exemption result and reason if a risk profile was included in your authorization request.

The table below describes the response parameters:

ParameterDescription
exemption.resultReturns honored, outOfScope, rejected or unknown
exemption.reasonFor 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

You must always store and use the link returned in the payments:cardOnFileAuthorize action link to authorize your next card on file payments.

Note

In case of an error, you can get further information in our error reference.


Next steps


Refund a payment

Card on file authorization without verification

Use our migrate card on file authorize resource when your customer is initiating a payment using stored card details without verifying their account first. Read more about card on file mandates here.

Card on file without verification authorization request

POST your card on file authorizations to our payments:migrateCardOnFileAuthorize action link resource received in your query the payments root resource request.

migrateCardOnFile authorization example request

POST https://try.access.worldpay.com/payments/authorizations/migrateCardOnFile

Note

Click the tabs below to see all the mandatory fields for all supported paymentInstrument parameters.

migrateCardOnFile authorization 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
            }
        }
    }
}

Parameter descriptions

ParameterRequiredDescription
channelThe payment channel indicates the interaction of the cardholder with the merchant. Possible value :
  • moto
Supply a value of 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.intentA parameter detailing the reason for entering into a repeat payment agreement. Possible value:
  • instalment
  • subscription
instruction.paymentInstrumentAn object that contains the payment type and details.
Available paymentInstruments:
  • card/plain
  • card/token - create a token first
  • card/checkout - Use our Checkout SDK for session creation and use this session to create a token first. You must use the token in the tokenHref not the Checkout session.
  • card/networkToken+applepay - Used for a decrypted wallet flow. This paymentInstrument includes the dpan which replaces the original card number. It is generated by the card network/ wallet provider.
scheme.referenceUnique 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, card/token and card/networkToken+applepay 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.
customer.authentication.typeUse card/networkToken for a decrypted wallet flow.

You can find the full parameter description here.

Optional parameters

Example Migrate Card on File Authorization request (all parameters)

The requests below contain all the mandatory and optional fields needed for a successful migrateCardOnFile authorization request.

Full migrateCardOnFile authorization 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"
    }
}

You can find all other parameter descriptions [here](#optional parameters).
For our 3DS parameter description click here.

Card on file without verification response

Best Practice

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 payment

You receive:

  • an HTTP code 201
  • an "outcome": "authorized"
  • 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 cancel, settle, partially settle or query payment events
  • 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

Note that if the paymentInstrument object is returned, there is no guarantee that each field listed below will be returned with every transaction.

ParameterDescription
paymentInstrument.typeThe type of paymentInstrument. Eg:
  • card/plain+masked
  • card/network+masked
  • card/network
paymentInstrument.card.brandThe card brand. Sometimes referred to as the network or scheme. Eg:
  • "visa"
  • "mastercard"
  • "amex"
paymentInstrument.card.number.binThe card bin. Eg:
444433
Note
this may contain the * character.
paymentInstrument.card.number.last4DigitsThe 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.monthThe card expiry month. Eg:
11
paymentInstrument.card.expiryDate.yearThe card expiry year. Eg:
2025
paymentInstrument.card.fundingTypeHow the card is funded. Eg:
  • credit
  • debit
  • prepaid
  • deferredDebit
  • chargeCard
paymentInstrument.card.categoryWhether the card is classed as a consumer card or a card for commercial use. Eg:
  • consumer
  • commercial
paymentInstrument.card.countryCodeThe 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.nameThe name of the card issuer. Eg:
Some Issuer PLC.
paymentInstrument.card.paymentAccountReferenceThe 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 payment

You receive:

Example response

{
    "outcome": "authorized",
    "riskFactors": [{
            "risk": "not_matched",
            "type": "cvc"
        },
        {
            "risk": "not_checked",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "not_checked",
            "detail": "address",
            "type": "avs"
        }
    ],
    "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:cancel": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:settle": {
            "href": "https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:partialSettle": {
            "href": "https://try.access.worldpay.com/payments/settlements/partials/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:events": {
            "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:cardOnFileAuthorize": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cardOnFile/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:recurringAuthorize": {
            "href": "https://try.access.worldpay.com/payments/authorizations/recurring/eyJrIjoiazNhYjYzMiJ9"
        },
        "curies": [{
            "name": "payments",
            "href": "https://try.access.worldpay.com/rels/payments/{rel}",
            "templated": true
        }]
    }
}

You can use the payments:settle action link to settle the payment straight away. Alternatively you can cache the response and use the link to settle the payment later.

You must store and use the link returned in the payments:migrateCardOnFileAuthorize action link to authorize your next card on file payments.

Note
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:

ParameterDescription
riskFactors.typeReturns avs, cvc or riskProfile
riskFactors.detailFor avs only.
Returns postcode or address
riskFactors.riskReturns not_checked, not_matched, not_supplied or verificationFailed

exemptions

An exemption result and reason if a risk profile was included in your authorization request.

The table below describes the response parameters:

ParameterDescription
exemption.resultReturns honored, outOfScope, rejected or unknown
exemption.reasonFor 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.


Next steps


Settle or cancel a payment