**Last updated**: 30 March 2026 | [**Change log**](/products/card-payments/changelog/) # Take a card payment New API version This documentation is for version 7 of the Card Payments API. If you're using [version 6](/products/card-payments/v6/authorize-a-payment), you can find information on how to upgrade in our [migration guide](/products/card-payments/v7-migration-guide). Take online card payments using our Card Payments API. ## Customer Initiated Transactions All payment requests where the cardholder actively participates in the flow are Customer Initiated Transactions (CITs). `POST` to our `customerInitiatedTransactions` endpoint to authorize a payment. Note Click the tabs below to see all the mandatory fields for the supported `paymentInstrument` parameters. `POST` `https://try.access.worldpay.com/cardPayments/customerInitiatedTransactions` ### Code examples Card ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/plain", "cardNumber": "4444333322221111", "expiryDate": { "month": 5, "year": 2035 } } } } ``` Token ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/token", "href": "https://try.access.worldpay.com/tokens/{}" } } } ``` Network token ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/networkToken", "tokenNumber": "4444333322221111", "expiryDate": { "month": 5, "year": 2035 } } }, "authentication": { "networkToken": { "cryptogram": "MAAAAAAAAAAAAAAAAAAAAAAAAAB=", "eci": "05" } } } ``` Checkout ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/checkout", "tokenHref": "https://try.access.worldpay.com/tokens/{}", "cvcHref": "https://try.access.worldpay.com/sessions/{}" } }, "authentication": { "threeDS": { "eci": "05", "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAA3=", "transactionId": "a09b446d-5c0d-4003-9c99-21fb73d75999", "version": "2.2.0" } } } ``` Apple Pay ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/wallet+applepay", "walletToken": "{\"version\": \"EC_v1\",\"data\": \"kdHd..GQ==\",\"signature\": \"MIAGCSqGSIb3DQEH...AAA\",\"header\": {\"transactionId\": \"d3b28af..f8\",\"ephemeralPublicKey\": \"MFkwE..Q==\",\"publicKeyHash\": \"dxCK..6o=\" }}" } } } ``` Google Pay ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/wallet+googlepay", "walletToken": "{\"protocolVersion\":\"ECv1\",\"signature\":\"MEQCIH6Q4OwQ0jAceFEkGF0JID6sJNXxOEi4r+mA7biRxqBQAiAondqoUpU/bdsrAOpZIsrHQS9nwiiNwOrr24RyPeHA0Q\\u003d\\u003d\",\"signedMessage\":\"{\\\"tag\\\":\\\"jpGz1F1Bcoi/fCNxI9n7Qrsw7i7KHrGtTf3NrRclt+U\\\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"BJatyFvFPPD21l8/uLP46Ta1hsKHndf8Z+tAgk+DEPQgYTkhHy19cF3h/bXs0tWTmZtnNm+vlVrKbRU9K8+7cZs\\\\u003d\\\",\\\"encryptedMessage\\\":\\\"mKOoXwi8OavZ\\\"}\"}" } } } ``` Apple Pay decrypted ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/networkToken+applepay", "tokenNumber": "4444333322221111", "expiryDate": { "month": 5, "year": 2035 } } }, "authentication": { "networkToken": { "cryptogram": "MAAAAAAAAAAAAAAAAAAAAAAAAAB=", "eci": "05" } } } ``` Google Pay decrypted ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/networkToken+googlepay", "tokenNumber": "4444333322221111", "expiryDate": { "month": 5, "year": 2035 } } }, "authentication": { "networkToken": { "cryptogram": "MAAAAAAAAAAAAAAAAAAAAAAAAAB=", "eci": "05" } } } ``` ### Schema (parameters) ```json { "$ref": "#/components/schemas/customerInitiatedTransaction", "components": { "schemas": { "transactionReference": { "maxLength": 64, "minLength": 1, "pattern": "^[-A-Za-z0-9_!@#$%()*=.:;?\\[\\]{}~`/+]*$", "type": "string", "description": "A unique reference generated by you that is used to identify a payment throughout its lifecycle." }, "orderReference": { "type": "string", "description": "A reference that you can apply to one or more payments according to your business needs. You may reuse the same reference across multiple payments, for example where:\n- the total amount for a single order is split across multiple payments\n- you use a single reference for each payment in a recurring agreement or split shipment scenario ", "maxLength": 64, "minLength": 1, "pattern": "^[-A-Za-z0-9_!@#$%()*=.:;?\\[\\]{}~/+]*$", "example": "order-12345" }, "entity": { "maxLength": 32, "minLength": 1, "pattern": "^([A-Za-z0-9]+[A-Za-z0-9 ]*)?$", "example": "default", "type": "string", "description": "Direct your payment to assist with billing, reporting and reconciliation. This is mandatory for authentication and queries." }, "mcc": { "pattern": "^\\d{4}$", "type": "string", "description": "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.", "maxLength": 4, "minLength": 4 }, "paymentFacilitator": { "required": [ "schemeId", "subMerchant" ], "type": "object", "description": "An object containing Payment Facilitator information. This information is required for every authorization **only if you are a Payment Facilitator**.", "properties": { "schemeId": { "maxLength": 11, "minLength": 1, "pattern": "[0-9]*$", "type": "string", "description": "Your payment facilitator ID received from Visa, Mastercard, or Amex." }, "independentSalesOrganizationId": { "maxLength": 11, "minLength": 1, "pattern": "[0-9]*$", "type": "string" }, "subMerchant": { "required": [ "reference", "name", "address" ], "type": "object", "properties": { "name": { "maxLength": 25, "minLength": 1, "pattern": "^(?!\\s*$)[A-Za-z0-9 ]*$", "type": "string" }, "reference": { "type": "string", "minLength": 1, "maxLength": 15, "pattern": "^[A-Za-z0-9]*$" }, "address": { "type": "object", "required": [ "postalCode", "street", "city", "countryCode" ], "properties": { "postalCode": { "maxLength": 10, "minLength": 1, "pattern": "^(?!\\s*$)[a-zA-Z0-9\\s]*$", "type": "string", "example": "SW1 1AA" }, "street": { "maxLength": 50, "minLength": 1, "pattern": "^(?!\\s*$)[A-Za-z0-9\\s]*$", "type": "string", "example": "221B Baker Street" }, "city": { "maxLength": 13, "minLength": 1, "pattern": "^(?!\\s*$)[A-Za-z\\s-]*$", "type": "string", "example": "London" }, "state": { "maxLength": 3, "minLength": 1, "pattern": "^[a-zA-Z0-9]*$", "type": "string", "description": "The state code of the subMerchant in ISO-3166-2 format." }, "countryCode": { "maxLength": 2, "minLength": 2, "pattern": "^[A-Z]*$", "type": "string", "description": "Country code of the subMerchant in [ISO 3166-1 Alpha-2 format](/products/reference/supported-countries-currencies#iso-country-codes)." } } }, "phoneNumber": { "maxLength": 20, "minLength": 4, "pattern": "^(?!\\s*$)[0-9\\s()+-/.x]*$", "type": "string" }, "taxReference": { "maxLength": 20, "minLength": 1, "pattern": "^(?!\\s*$)[a-zA-Z0-9\\s-]*$", "type": "string" }, "email": { "maxLength": 40, "minLength": 1, "type": "string", "pattern": "^.+@.+$" }, "url": { "maxLength": 255, "minLength": 1, "pattern": "^[a-zA-Z0-9@!£*#$)(+-_=.,/;:]*$", "type": "string" } } } } }, "taxReference": { "maxLength": 20, "minLength": 1, "pattern": "^(?!\\s*$)[a-zA-Z0-9\\s-]*$", "type": "string", "description": "Merchant's tax reference." }, "value": { "required": [ "amount", "currency" ], "type": "object", "description": "An object that contains information about the value of the payment.", "properties": { "amount": { "type": "integer", "description": "The payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50.", "example": 250 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]$", "description": " The three character currency code. See list of [supported currencies](/products/reference/supported-countries-currencies#iso-currency-codes).", "example": "USD" } } }, "narrative": { "required": [ "line1" ], "type": "object", "description": "The text that appears on your customer's statement. Used to identify the merchant.", "properties": { "line1": { "type": "string", "minLength": 1, "maxLength": 24, "pattern": "^[a-zA-Z0-9 _!@#$%()*=.:;?[]{}~/+-,`^&]*$", "description": "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)." }, "line2": { "type": "string", "minLength": 1, "maxLength": 24, "pattern": "^[a-zA-Z0-9 _!@#$%()*=.:;?[]{}~/+-,`^&]*$", "description": "Additional details about the payment e.g. order number, telephone number." } } }, "cardNumber": { "type": "string", "maxLength": 19, "minLength": 12, "pattern": "^[0-9]+$", "description": "Your customer's card number. Sometimes referred to as Primary Account Number (PAN)." }, "cardHolderName": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The cardholder's name as it appears on their card." }, "expiryDateCard": { "required": [ "month", "year" ], "type": "object", "description": "Contains your customer's card expiry date.", "properties": { "month": { "type": "integer", "pattern": "^([1-9]|1[0-2])$", "example": 7 }, "year": { "type": "integer", "pattern": "^([1-9]{1}[0-9]{3})$", "example": 2050 } } }, "billingAddress": { "required": [ "postalCode", "countryCode" ], "type": "object", "description": "Contains the billing address information.", "properties": { "address1": { "type": "string", "description": "First line of the address. Required if `city` is provided." }, "address2": { "type": "string", "description": "Second line of the address." }, "address3": { "type": "string", "description": "Third line of the address." }, "city": { "type": "string", "description": "City. Required if `address1` is provided." }, "postalCode": { "type": "string", "description": "Post code. Required, but an empty value can be provided for specific countries (e.g., `IE`)." }, "state": { "type": "string", "description": "State/province in max 3 characters." }, "countryCode": { "type": "string", "description": "Must be provided in [ISO 3166-1 Alpha-2 format](/products/reference/supported-countries-currencies#iso-country-codes)." }, "phoneNumber": { "type": "string", "description": "Phone number.", "minLength": 3, "maxLength": 20, "pattern": "^[0-9()+-/.x ]+$" } } }, "cvc": { "type": "string", "maxLength": 4, "minLength": 3, "pattern": "^[0-9]+$", "description": "CVC is a unique set of 3 or 4 numbers used to verify the card. Our API checks to see if the CVC supplied matches the CVC held by the issuing bank." }, "card_plain": { "required": [ "type", "cardNumber", "expiryDate" ], "type": "object", "properties": { "type": { "enum": [ "card/plain" ], "type": "string", "description": "An identifier for the `paymentInstrument` being used." }, "cardNumber": { "$ref": "#/components/schemas/cardNumber" }, "cardHolderName": { "$ref": "#/components/schemas/cardHolderName" }, "expiryDate": { "$ref": "#/components/schemas/expiryDateCard" }, "billingAddress": { "$ref": "#/components/schemas/billingAddress" }, "cvc": { "$ref": "#/components/schemas/cvc" } } }, "card_token": { "required": [ "type", "href" ], "type": "object", "properties": { "type": { "enum": [ "card/token" ], "type": "string", "description": "An identifier for the `paymentInstrument` being used." }, "href": { "type": "string", "description": "An `http` address that contains your link to an Access Token." }, "cvc": { "$ref": "#/components/schemas/cvc" } } }, "tokenNumber": { "type": "string", "maxLength": 19, "minLength": 12, "pattern": "^[0-9]+$", "description": "The network token number." }, "expiryDateToken": { "required": [ "month", "year" ], "type": "object", "description": "Contains your customer's token expiry date.", "properties": { "month": { "type": "integer", "pattern": "^([1-9]|1[0-2])$", "example": 7 }, "year": { "type": "integer", "pattern": "^([1-9]{1}[0-9]{3})$", "example": 2050 } } }, "card_networkToken": { "required": [ "type", "tokenNumber", "expiryDate" ], "type": "object", "properties": { "type": { "enum": [ "card/networkToken" ], "type": "string", "description": "An identifier for the `paymentInstrument` being used." }, "tokenNumber": { "$ref": "#/components/schemas/tokenNumber" }, "expiryDate": { "$ref": "#/components/schemas/expiryDateToken" }, "billingAddress": { "$ref": "#/components/schemas/billingAddress" }, "cardHolderName": { "$ref": "#/components/schemas/cardHolderName" } } }, "card_checkout": { "required": [ "type", "tokenHref" ], "type": "object", "properties": { "type": { "enum": [ "card/checkout" ], "type": "string" }, "tokenHref": { "type": "string" }, "cvcHref": { "type": "string" } } }, "card_wallet_applepay": { "required": [ "type", "walletToken" ], "type": "object", "properties": { "type": { "enum": [ "card/wallet+applepay" ], "type": "string" }, "walletToken": { "type": "string", "description": "The encrypted wallet token returned by Apple", "example": "{\"version\": \"EC_v1\",\"data\": \"kdHd..GQ==\",\"signature\": \"MIAGCSqGSIb3DQEH...AAA\",\"header\": {\"transactionId\": \"d3b28af..f8\",\"ephemeralPublicKey\": \"MFkwE..Q==\",\"publicKeyHash\": \"dxCK..6o=\"}}" }, "billingAddress": { "$ref": "#/components/schemas/billingAddress" } } }, "card_wallet_googlepay": { "required": [ "type", "walletToken" ], "type": "object", "properties": { "type": { "enum": [ "card/wallet+googlepay" ], "type": "string" }, "walletToken": { "type": "string", "description": "The encrypted wallet token returned by Google", "example": "{\"protocolVersion\":\"ECv1\",\"signature\":\"MEQCIH6Q4OwQ0jAceFEkGF0JID6sJNXxOEi4r+mA7biRxqBQAiAondqoUpU/bdsrAOpZIsrHQS9nwiiNwOrr24RyPeHA0Q\\u003d\\u003d\",\"signedMessage\":\"{\\\"tag\\\":\\\"jpGz1F1Bcoi/fCNxI9n7Qrsw7i7KHrGtTf3NrRclt+U\\\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"BJatyFvFPPD21l8/uLP46Ta1hsKHndf8Z+tAgk+DEPQgYTkhHy19cF3h/bXs0tWTmZtnNm+vlVrKbRU9K8+7cZs\\\\u003d\\\",\\\"encryptedMessage\\\":\\\"mKOoXwi8OavZ\\\"}\"}" }, "billingAddress": { "$ref": "#/components/schemas/billingAddress" } } }, "card_networkToken_applepay": { "required": [ "type", "tokenNumber", "expiryDate" ], "type": "object", "properties": { "type": { "enum": [ "card/networkToken+applepay" ], "type": "string" }, "tokenNumber": { "$ref": "#/components/schemas/tokenNumber" }, "expiryDate": { "$ref": "#/components/schemas/expiryDateToken" }, "billingAddress": { "$ref": "#/components/schemas/billingAddress" }, "cardHolderName": { "$ref": "#/components/schemas/cardHolderName" } } }, "card_networkToken_googlepay": { "required": [ "type", "tokenNumber", "expiryDate" ], "type": "object", "properties": { "type": { "enum": [ "card/networkToken+googlepay" ], "type": "string" }, "tokenNumber": { "$ref": "#/components/schemas/tokenNumber" }, "expiryDate": { "$ref": "#/components/schemas/expiryDateToken" }, "billingAddress": { "$ref": "#/components/schemas/billingAddress" }, "cardHolderName": { "$ref": "#/components/schemas/cardHolderName" } } }, "cit_cardOnFile": { "required": [ "type", "storedCardUsage" ], "properties": { "type": { "type": "string", "description": "The processing arrangement agreed with your customer." }, "storedCardUsage": { "type": "string", "description": "Set to `first` to store a card or `subsequent` to use a previously stored card.", "enum": [ "first", "subsequent" ] } } }, "cit_subscription": { "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The processing arrangement agreed with your customer. A subscription plan occurs at fixed time intervals." }, "storedCardUsage": { "type": "string", "description": "Must be set to `first` to begin a new subscription.", "enum": [ "first" ] } } }, "cit_installment": { "type": "object", "required": [ "type", "installmentType" ], "properties": { "type": { "type": "string", "description": "The processing arrangement agreed with your customer." }, "installmentType": { "type": "string", "description": "Defines the type of installments service", "enum": [ "merchant", "latinAmerica" ] }, "installmentPlan": { "type": "object", "description": "Required only for `latinAmerica` installment type.", "required": [ "numberOfInstallments" ], "properties": { "numberOfInstallments": { "type": "integer", "description": "Number of installments that the requested amount should be broken into." } } }, "storedCardUsage": { "type": "string", "description": "Specifies the card on file agreement. Must be set to `first` to begin a new merchant installment (optional for `latinAmerica` installments).", "enum": [ "first", "subsequent" ] } } }, "consumerBillPayment": { "type": "boolean", "description": "Consumer Bill Payment is a flag which identifies a bill payment paid by providers on behalf of consumers." }, "debtRepayment": { "type": "boolean", "description": "Debt Repayment Indicator is a flag which identifies a payment with the purpose of repaying a debt." }, "requestAccountUpdater": { "type": "boolean", "description": "Allows you to request a real-time account update when using a previously stored card. You can only use this with `customerAgreement` transactions with a `storedCardUsage` value of `subsequent`. If the stored card details that you provided for the transaction are no longer valid and new credentials are available, the authorization will be processed with the new card and its details will be returned in the `updatedPaymentInstrument` object in the response." }, "fundsTransfer_bankAccount": { "type": "object", "properties": { "type": { "enum": [ "bankAccount" ], "type": "string" }, "identifierType": { "type": "string", "enum": [ "iban", "swift", "routingNumber", "accountNumber" ] }, "iban": { "maxLength": 34, "minLength": 1, "pattern": "^[a-zA-Z0-9]*$", "type": "string", "description": "The International Bank Account Number (IBAN) of the recipient. Required if `identifierType` is `iban`.", "example": "IE12BOFI90000112345678" }, "accountNumber": { "maxLength": 39, "minLength": 1, "pattern": "^[a-zA-Z0-9]*$", "type": "string", "description": "The account number of the recipient. Required if `identifierType` is `routingNumber`, `swift` or `accountNumber`. Visa requires the value to be a maximum of 34 characters. ", "example": "01234567" }, "swiftBic": { "maxLength": 11, "minLength": 8, "pattern": "^[a-zA-Z0-9]*$", "type": "string", "description": "The SWIFT Bank Identification Code (BIC) of the recipient. Required if `identifierType` is `swift`. Must be either 8 or 11 alphanumeric characters.", "example": "BEASUS33xxx" }, "routingNumber": { "maxLength": 9, "minLength": 9, "pattern": "^[0-9]*$", "type": "string", "description": "The ABA (American Bankers Association) Routing Transit Number (RTN). Identifies the Financial Insititution of the recipient's account. Required if `identifierType` is `routingNumber`. Must be 9 numeric characters.", "example": "111000025" } }, "required": [ "type", "identifierType" ] }, "fundsTransfer_card": { "type": "object", "properties": { "type": { "enum": [ "card" ], "type": "string" }, "cardNumber": { "maxLength": 19, "minLength": 12, "pattern": "^[0-9]*$", "type": "string", "description": "Recipient's card number." } }, "required": [ "type", "cardNumber" ] }, "fundsTransfer_wallet": { "type": "object", "properties": { "type": { "enum": [ "wallet" ], "type": "string" }, "walletReference": { "maxLength": 50, "minLength": 1, "pattern": "^[A-Za-z0-9@!£$*#)(+\\-_=.,/:;\"]*$", "type": "string", "description": "A reference identifying the destination wallet. Visa requires the value to be a maximum of 34 characters." } }, "required": [ "type", "walletReference" ] }, "fundsTransfer_storedValueWallet": { "type": "object", "properties": { "type": { "enum": [ "storedValueWallet" ], "type": "string" }, "walletReference": { "maxLength": 50, "minLength": 1, "pattern": "^[a-zA-Z0-9]*$", "type": "string", "description": "A reference identifying the destination wallet. Visa requires the value to be a maximum of 34 characters." } }, "required": [ "type", "walletReference" ] }, "fundsTransfer_stagedDigitalWallet": { "type": "object", "properties": { "type": { "enum": [ "stagedDigitalWallet" ], "type": "string" }, "walletReference": { "maxLength": 50, "minLength": 1, "pattern": "^[a-zA-Z0-9]*$", "type": "string", "description": "A reference identifying the destination wallet. Visa requires the value to be a maximum of 34 characters." } }, "required": [ "type", "walletReference" ] }, "fundsTransfer_merchantWallet": { "type": "object", "properties": { "type": { "enum": [ "merchantWallet" ], "type": "string" }, "walletReference": { "maxLength": 50, "minLength": 1, "pattern": "^[a-zA-Z0-9]*$", "type": "string", "description": "A reference identifying the destination wallet. Visa requires the value to be a maximum of 34 characters." } }, "required": [ "type", "walletReference" ] }, "fundsTransfer_email": { "type": "object", "properties": { "type": { "enum": [ "email" ], "type": "string" }, "emailAddress": { "maxLength": 40, "minLength": 1, "type": "string", "description": "Recipient's email address. Visa requires the value to be a maximum of 34 characters." } }, "required": [ "type", "emailAddress" ] }, "fundsTransfer_phone": { "type": "object", "properties": { "type": { "enum": [ "phone" ], "type": "string" }, "phoneNumber": { "maxLength": 20, "minLength": 3, "type": "string", "description": "Recipient's phone number.", "pattern": "^[0-9 ()+\\-/.x]+$" } }, "required": [ "type", "phoneNumber" ] }, "fundsTransfer_socialNetwork": { "type": "object", "properties": { "type": { "enum": [ "socialNetwork" ], "type": "string" }, "socialNetworkReference": { "maxLength": 50, "minLength": 1, "pattern": "^[a-zA-Z0-9]*$", "type": "string", "description": "A reference identifying recipient's social network account. Visa requires the value to be a maximum of 34 characters." } }, "required": [ "type", "socialNetworkReference" ] }, "fundsTransfer": { "type": "object", "description": "Contains details of the funds transfer request, which is a money movement for a reason other than the purchase of goods or services (also known as Account Funding Transaction (AFT)).", "required": [ "type" ], "properties": { "type": { "description": "Specifies the type of the funds transfer. {% admonition type=\"warning\" name=\"Note\" %} You may only submit the `fundsTransfer.type` values that relate to the use cases that you have been approved for by the schemes.{% /admonition %}", "enum": [ "accountToAccount", "cash", "disbursement", "personToPerson", "purchase", "topUp", "walletLoad" ], "type": "string", "x-enumDescriptions": { "accountToAccount": "Move funds to another financial institution account owned by the same person", "cash": "A card is used to fund a transfer where funds are given to the recipient in cash", "disbursement": "A card is used as the source of funds for a disbursement", "personToPerson": "Move funds to an account owned by another person (eg gifts)", "purchase": "For the initial purchase of a reloadable account (such as prepaid or gift card), or direct crypto & liquid asset purchases without an intermediary wallet load", "topUp": "Top up a pre-paid or debit card", "walletLoad": "Move funds to a digital wallet owned by the same person" } }, "purpose": { "description": "Specifies the purpose of the funds transfer. Required for some regions and use cases (eg crypto).", "enum": [ "businessToBusiness", "creditCardRepayment", "crypto", "crowdLending", "debitCard", "education", "emergency", "familySupport", "gift", "giftCard", "gaming", "highRiskSecurities", "liquidAssets", "medical", "payroll", "prepaidCard", "salary", "savings", "travel", "other" ], "type": "string" }, "recipient": { "type": "object", "description": "An object containing details about the recipient of funds, including name and address information, as well as recipient account details. In many use cases, the recipient is the same person as the sender (for example if your customer uses their card to load funds into their own crypto exchange or investment account). __Although an optional object in the API schema, `recipient` is required for some regions and use cases.__", "properties": { "account": { "type": "object", "description": "An object for the account details of the recipient.", "oneOf": [ { "$ref": "#/components/schemas/fundsTransfer_bankAccount" }, { "$ref": "#/components/schemas/fundsTransfer_card" }, { "$ref": "#/components/schemas/fundsTransfer_wallet" }, { "$ref": "#/components/schemas/fundsTransfer_storedValueWallet" }, { "$ref": "#/components/schemas/fundsTransfer_stagedDigitalWallet" }, { "$ref": "#/components/schemas/fundsTransfer_merchantWallet" }, { "$ref": "#/components/schemas/fundsTransfer_email" }, { "$ref": "#/components/schemas/fundsTransfer_phone" }, { "$ref": "#/components/schemas/fundsTransfer_socialNetwork" } ], "discriminator": { "propertyName": "type", "mapping": { "bankAccount": "#/components/schemas/fundsTransfer_bankAccount", "card": "#/components/schemas/fundsTransfer_card", "wallet": "#/components/schemas/fundsTransfer_wallet", "storedValueWallet": "#/components/schemas/fundsTransfer_storedValueWallet", "stagedDigitalWallet": "#/components/schemas/fundsTransfer_stagedDigitalWallet", "merchantWallet": "#/components/schemas/fundsTransfer_merchantWallet", "email": "#/components/schemas/fundsTransfer_email", "phone": "#/components/schemas/fundsTransfer_phone", "socialNetwork": "#/components/schemas/fundsTransfer_socialNetwork" } } }, "firstName": { "maxLength": 35, "minLength": 1, "pattern": "^[-A-Za-z0-9_!@#$%()*=.:;?\\[\\]{}~`/+]*$", "type": "string", "description": "Recipient's first name. Must be supplied if `lastName` or `middleName` are provided." }, "middleName": { "maxLength": 35, "minLength": 1, "pattern": "^[-A-Za-z0-9_!@#$%()*=.:;?\\[\\]{}~`/+]*$", "type": "string", "description": "Recipient's middle name." }, "lastName": { "maxLength": 35, "minLength": 1, "pattern": "^[-A-Za-z0-9_!@#$%()*=.:;?\\[\\]{}~`/+]*$", "type": "string", "description": "Recipient's last name. Must be supplied if `firstName` or `middleName` are provided." }, "address": { "type": "object", "description": "The recipient's address.", "properties": { "address1": { "maxLength": 255, "minLength": 1, "pattern": "^[a-zA-Z0-9 ]*$", "type": "string", "description": "Must be supplied if `city` is provided." }, "address2": { "maxLength": 255, "minLength": 1, "pattern": "^[a-zA-Z0-9 ]*$", "type": "string" }, "city": { "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9 ]*$", "type": "string", "description": "Must be supplied if `address1` is provided." }, "postalCode": { "maxLength": 10, "minLength": 1, "pattern": "^[a-zA-Z0-9 ]*$", "type": "string" }, "state": { "maxLength": 3, "minLength": 1, "pattern": "^[a-zA-Z0-9]*$", "type": "string", "description": "1-3 alphanumeric characters and spaces." }, "countryCode": { "maxLength": 2, "minLength": 2, "pattern": "^[A-Z]*$", "type": "string", "description": "Country code in [ISO 3166-1 Alpha-2 format](/products/reference/supported-countries-currencies#iso-country-codes)." } }, "required": [ "countryCode" ] }, "dateOfBirth": { "type": "object", "description": "Recipient's date of birth.", "properties": { "day": { "type": "integer" }, "month": { "type": "integer" }, "year": { "type": "integer" } }, "required": [ "day", "month", "year" ] }, "phoneNumber": { "type": "string", "description": "Recipient's phone number.", "maxLength": 20, "minLength": 3, "pattern": "^[0-9 ()+\\-/.x]*$" }, "documentReference": { "maxLength": 25, "minLength": 1, "type": "string", "description": "Recipient's document reference (e.g. Tax ID).", "pattern": "^[A-Za-z0-9\\-\\/+.()]*$" } } }, "sender": { "type": "object", "description": "An object containing details about the sender of funds, including name and address information. The sender account is always the card account declared within `instruction.paymentInstrument`. __Although an optional object in the API schema, `sender` is required for some regions and use cases.__", "properties": { "firstName": { "maxLength": 35, "minLength": 1, "pattern": "^[-A-Za-z0-9_!@#$%()*=.:;?\\[\\]{}~`/+]*$", "type": "string", "description": "Sender's first name. Must be supplied if `lastName` or `middleName` are provided." }, "middleName": { "maxLength": 35, "minLength": 1, "pattern": "^[-A-Za-z0-9_!@#$%()*=.:;?\\[\\]{}~`/+]*$", "type": "string", "description": "Sender's middle name." }, "lastName": { "maxLength": 35, "minLength": 1, "pattern": "^[-A-Za-z0-9_!@#$%()*=.:;?\\[\\]{}~`/+]*$", "type": "string", "description": "Sender's last name. Must be supplied if `firstName` or `middleName` are provided." }, "address": { "type": "object", "description": "The sender's address.", "properties": { "address1": { "maxLength": 255, "minLength": 1, "pattern": "^[a-zA-Z0-9 ]*$", "type": "string", "description": "Must be supplied if `city` is provided." }, "address2": { "maxLength": 255, "minLength": 1, "pattern": "^[a-zA-Z0-9 ]*$", "type": "string" }, "city": { "maxLength": 100, "minLength": 1, "pattern": "^[a-zA-Z0-9 ]*$", "type": "string", "description": "Must be supplied if `address1` is provided." }, "postalCode": { "maxLength": 10, "minLength": 1, "pattern": "^[a-zA-Z0-9 ]*$", "type": "string" }, "state": { "maxLength": 3, "minLength": 1, "pattern": "^[a-zA-Z0-9]*$", "type": "string", "description": "1-3 alphanumeric characters and spaces." }, "countryCode": { "maxLength": 2, "minLength": 2, "pattern": "^[A-Z]*$", "type": "string", "description": "Country code in [ISO 3166-1 Alpha-2 format](/products/reference/supported-countries-currencies#iso-country-codes)." } }, "required": [ "countryCode" ] }, "dateOfBirth": { "type": "object", "description": "Sender's date of birth.", "properties": { "day": { "type": "integer" }, "month": { "type": "integer" }, "year": { "type": "integer" } }, "required": [ "day", "month", "year" ] }, "documentReference": { "maxLength": 25, "minLength": 1, "type": "string", "description": "Sender's document reference (e.g. Tax ID)." } } } } }, "routing": { "type": "object", "description": "An object containing specific routing preferences.", "properties": { "fundingType": { "type": "string", "description": "Specifies the credit or debit functionality of a combo card.", "enum": [ "credit", "debit" ] }, "preferredCardBrand": { "type": "string", "enum": [ "visa", "mastercard", "maestro", "amex", "cartesBancaires", "diners", "dankort", "jcb", "discover", "elo", "eftposAU", "unionPay" ], "description": "Specifies your customer's preferred card brand to be used for the transaction using a co-badged card." } } }, "southKorea_personalAuth": { "required": [ "type", "firstTwoOfPin", "dateOfBirth" ], "type": "object", "properties": { "type": { "type": "string", "description": "Personal card issued in South Korea.", "enum": [ "southKorea/personal" ] }, "firstTwoOfPin": { "type": "string", "description": "The first two characters of the card's PIN.", "minLength": 2, "maxLength": 2, "example": "34", "pattern": "^[0-9]{2}$" }, "dateOfBirth": { "type": "object", "description": "Cardholder's date of birth.", "required": [ "day", "month", "year" ], "properties": { "day": { "type": "integer", "example": 1 }, "month": { "type": "integer", "example": 1 }, "year": { "type": "integer", "example": 1900 } } } } }, "southKorea_corporateAuth": { "required": [ "firstTwoOfPin", "businessRegistrationNumber", "type" ], "type": "object", "properties": { "type": { "type": "string", "description": "Corporate card issued in South Korea.", "enum": [ "southKorea/corporate" ] }, "firstTwoOfPin": { "type": "string", "description": "The first two characters of the card's PIN.", "minLength": 2, "maxLength": 2, "example": "34", "pattern": "^[0-9]{2}$" }, "businessRegistrationNumber": { "type": "string", "description": "A unique identifier assigned to businesses when they register with the Korean tax authorities.", "minLength": 6, "maxLength": 10 } } }, "exemption": { "type": "object", "required": [ "type" ], "description": "An object for applying exemptions. If you are applying a TRA (Transaction Risk Assessment) exemption granted by us, use the `riskProfile` object", "oneOf": [ { "$ref": "#/components/schemas/exemption_external" }, { "$ref": "#/components/schemas/exemption_authentication-outage" } ], "discriminator": { "propertyName": "type", "mapping": { "external": "#/components/schemas/exemption_external", "authenticationOutage": "#/components/schemas/exemption_authentication-outage" } } }, "exemption_type": { "type": "string", "x-enumDescriptions": { "external": "TRA (Transaction Risk Assessment) exemption provided by a 3rd party provider", "authenticationOutage": "Apply an exemption for recognized downstream 3DS authentication failures. This will increase the likelihood of receiving a successful authorization, but will not provide liability shift." } }, "exemption_external": { "allOf": [ { "$ref": "#/components/schemas/exemption" } ], "type": "object", "properties": { "type": { "$ref": "#/components/schemas/exemption_type" }, "request": { "type": "object", "description": "The type of exemption to apply", "properties": { "placement": { "enum": [ "authorization", "authentication" ], "x-enumDescriptions": { "authorization": "Apply the exemption in the payment authorization", "authentication": "The exemption has been applied in 3DS authentication" }, "type": "string", "description": "Indicates whether the exemption should be placed in a payment authorization or 3DS authentication. \n" }, "type": { "enum": [ "lowValue", "lowRisk" ], "x-enumDescriptions": { "lowValue": "Apply a lowValue exemption (authorization exemption only)", "lowRisk": "Apply a lowRisk exemption" }, "type": "string", "description": "The type of exemption to apply." } } } } }, "exemption_authentication-outage": { "allOf": [ { "$ref": "#/components/schemas/exemption" } ], "type": "object", "properties": { "type": { "$ref": "#/components/schemas/exemption_type" } } }, "shipping": { "type": "object", "description": "An object containing shipping details.", "properties": { "sender": { "type": "object", "properties": { "address": { "type": "object", "description": "An object containing sender's (shipped from) address.", "properties": { "postalCode": { "maxLength": 10, "minLength": 1, "pattern": "^[a-zA-Z0-9 ]*$", "type": "string" } } } } }, "recipient": { "type": "object", "properties": { "address": { "type": "object", "description": "An object containing recipient's shipping address.", "properties": { "countryCode": { "maxLength": 2, "minLength": 2, "pattern": "^[A-Z]*$", "type": "string" }, "postalCode": { "maxLength": 10, "minLength": 1, "pattern": "^[a-zA-Z0-9 ]*$", "type": "string" } } } } } } }, "order": { "type": "object", "description": "An object containing details about the order.", "properties": { "taxExempt": { "type": "boolean", "description": "A flag to indicate whether the purchase is exempt from tax. Must be set to `true` if `order.salesTax` is 0." }, "orderDate": { "type": "object", "description": "Date of the order.", "properties": { "day": { "type": "integer" }, "month": { "type": "integer" }, "year": { "type": "integer" } }, "required": [ "day", "month", "year" ] }, "items": { "description": "Array of order items. You can send up to 99 individual order objects within this array.", "items": { "type": "object", "required": [ "name" ], "properties": { "commodityCode": { "maxLength": 12, "minLength": 1, "type": "string", "description": "Commodity code as defined by the National Institute of Governmental Purchasing.", "pattern": "^[A-Za-z0-9@!£*#$)(-+_=.,/;:'\"]{1,12}$", "example": "ABC123@#" }, "totalTaxAmount": { "type": "integer", "description": "Total tax amount for the item(s)." }, "unitCost": { "type": "integer", "description": "The price of one unit of the item purchased." }, "totalAmount": { "type": "integer", "description": "Total cost of the item(s) including tax." }, "totalAmountNoTax": { "type": "integer", "description": "Total cost of the item(s) excluding tax." }, "unitOfMeasure": { "maxLength": 8, "minLength": 1, "type": "string", "description": "The unit of measure of the purchased item. Explains how to interpret `items.quantity` field, e.g. quantity = 15, unitOfMeasure = kg.", "pattern": "^[A-Za-z0-9@!£*#$)(+_=.,/;:'\"-]{1,8}$" }, "name": { "maxLength": 26, "minLength": 1, "type": "string", "description": "Name of the item(s).", "pattern": "^[A-Za-z0-9 @!£*#$)(+_=.,/;:'\"-]{1,26}$" }, "quantity": { "type": "integer", "description": "Number of items purchased." }, "productCode": { "maxLength": 12, "minLength": 1, "type": "string", "description": "Merchant defined product code.", "pattern": "^[A-Za-z0-9@!£*#\\$)(+_=.,/;:'\"-]{1,12}$" }, "totalDiscountAmount": { "type": "integer", "description": "Total discount amount for the item(s)." } } }, "type": "array" }, "dutyAmount": { "type": "integer", "description": "Total amount of duty costs for the order." }, "salesTax": { "type": "integer", "description": "Total amount of sales tax for the order. Must be provided if `merchant.taxReference` is supplied." }, "shippingAmount": { "type": "integer", "description": "Total amount of shipping costs for the order." }, "invoiceReference": { "maxLength": 15, "minLength": 1, "type": "string", "description": "Invoice reference for the order.", "pattern": "^[A-Za-z0-9 @!£*#\\$)\\(+_=.,/;:'\"-]{1,15}$" }, "discountAmount": { "type": "integer", "description": "Total amount of discounts for the order." } } }, "recipient": { "type": "object", "description": "Additional transaction recipient data.", "properties": { "accountReference": { "maxLength": 10, "minLength": 1, "pattern": "^[a-zA-Z0-9]*$", "type": "string", "description": "Partial account reference of the primary recipient. Either partial card number (first 6 and last 4, no spaces), or a bank account number", "example": "4444331111" }, "lastName": { "maxLength": 60, "minLength": 1, "pattern": "^[a-zA-Z@!£*#$)(+-_=.,/;:'\" ]*$", "type": "string", "description": "The last name of the recipient. If for a business, then use the company name.", "example": "Smith" }, "address": { "type": "object", "description": "Address of the recipient.", "required": [ "postalCode" ], "properties": { "postalCode": { "maxLength": 7, "minLength": 5, "pattern": "^[A-Z0-9 ]*$", "type": "string", "description": "The postal code of the recipient (UK only)" } } }, "dateOfBirth": { "type": "object", "description": "Birth date of the recipient.", "required": [ "day", "month", "year" ], "properties": { "day": { "type": "integer" }, "month": { "type": "integer" }, "year": { "type": "integer" } } } } }, "industryData": { "type": "object", "description": "An object containing industry specific order data.", "properties": { "type": { "enum": [ "airline" ], "type": "string" }, "airlineName": { "type": "string", "description": "The name of the airline (displayed as it would be on a bill).", "example": "Cobb Air", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9 @!£*#\\$()\\+\\-_=.,\\/;:'\"]+$" }, "ticket": { "type": "object", "description": "An object containing ticket details.", "properties": { "number": { "type": "string", "description": "The ticket number.", "example": "123", "minLength": 1, "maxLength": 16, "pattern": "^[A-Za-z0-9]+$" }, "issuerAddress": { "type": "object", "description": "An object containing the ticket issuer's address.", "properties": { "address1": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[A-Za-z0-9 ]+$" }, "city": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9 ]+$" }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$" }, "postalCode": { "type": "string", "minLength": 1, "maxLength": 10, "pattern": "^[A-Za-z0-9 ]+$" } }, "required": [ "address1", "city", "countryCode", "postalCode" ] }, "flightDetails": { "description": "An array with objects containing flight details. Each object represents one leg of a flight and you can submit up to four flight legs within this array.", "items": { "type": "object", "properties": { "fareClassCode": { "type": "string", "description": "The code used by airlines to identity a fare type.", "minLength": 1, "maxLength": 15, "pattern": "^[A-Za-z0-9]+$" }, "departureAirport": { "type": "string", "description": "The three letter IATA Airport Code for the departure airport.", "example": "LHR", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$" }, "arrivalAirport": { "type": "string", "description": "The three letter IATA Airport Code for the destination airport.", "example": "SYD", "minLength": 3, "maxLength": 3, "pattern": "^[A-Z]{3}$" }, "carrierCode": { "type": "string", "description": "Same as `industryData.airlineCode`, the code represents the airline for the specific flight leg.", "example": "M1", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$" }, "fareBasisCode": { "type": "string", "description": "An optional extension to the `fareClassCode` for custom codes.", "example": "TMYA", "minLength": 1, "maxLength": 15, "pattern": "^[A-Za-z0-9]+$" }, "flightCode": { "type": "string", "description": "The flight code.", "example": "501", "minLength": 1, "maxLength": 5, "pattern": "^[0-9]+$" }, "departureDate": { "type": "object", "description": "An object containing the date of the departure.", "properties": { "day": { "type": "integer" }, "month": { "type": "integer" }, "year": { "type": "integer" } }, "required": [ "day", "month", "year" ] }, "stopOver": { "type": "boolean", "description": "Set to `true` if this flight leg is a stopover, connecting different destinations." }, "taxAmount": { "type": "integer", "description": "The tax amount for this specific flight leg.", "example": 3500 } }, "required": [ "carrierCode", "flightCode", "departureAirport", "arrivalAirport", "departureDate", "fareClassCode", "taxAmount" ] }, "type": "array" }, "restricted": { "type": "boolean", "description": "Typically, restricted airfares require approval and e-ticket processing within 24 hours of making the reservation, are not transferable if cancelled, and can have specific requirements on when or whether a cancelled ticket can be rebooked. You must define if the ticket is restricted, but this does not affect the payment flows." }, "issueDate": { "type": "object", "description": "An object containing the ticket's issue date.", "properties": { "day": { "type": "integer" }, "month": { "type": "integer" }, "year": { "type": "integer" } }, "required": [ "day", "month", "year" ] } }, "required": [ "number", "restricted", "issuerAddress" ] }, "agentName": { "type": "string", "description": "The name of the travel agent.", "example": "J Small and Co", "minLength": 1, "maxLength": 26, "pattern": "^[A-Za-z0-9 @!£*#\\$()\\+\\-_=.,\\/;:'\"]+$" }, "agentCode": { "type": "string", "description": "The IATA travel agency code.", "example": "12345678", "minLength": 1, "maxLength": 8, "pattern": "^[0-9]+$" }, "invoiceReference": { "type": "string", "description": "Billing Settlement Plan invoice reference.", "minLength": 1, "maxLength": 14, "pattern": "^[A-Za-z0-9]+$" }, "airlineCode": { "type": "string", "description": "The two character IATA airline code.", "example": "CA", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$" }, "passenger": { "type": "object", "description": "An object containing passenger details.", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 15, "pattern": "^[A-Za-z0-9]+$" }, "firstName": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[A-Za-z @!£*#\\$()\\+\\-_=.,\\/;:'\"]+$" }, "lastName": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[A-Za-z @!£*#\\$()\\+\\-_=.,\\/;:'\"]+$" } }, "required": [ "code", "firstName", "lastName" ] } }, "required": [ "type", "ticket", "airlineName", "airlineCode", "agentCode", "passenger" ] }, "customerInitiatedTransaction": { "required": [ "transactionReference", "merchant", "instruction", "channel" ], "type": "object", "properties": { "transactionReference": { "$ref": "#/components/schemas/transactionReference" }, "orderReference": { "$ref": "#/components/schemas/orderReference" }, "channel": { "enum": [ "ecom", "moto" ], "type": "string", "description": "Interaction between the cardholder and you. Supply a value of `ecom` to process an eCommerce authorization. Supply a value of `moto` to process an authorization as a Mail Order or Telephone Order transaction. Note: 3DS `authentication` cannot be supplied for MOTO payments." }, "merchant": { "required": [ "entity" ], "type": "object", "description": "An object that contains information about the merchant.", "properties": { "entity": { "$ref": "#/components/schemas/entity" }, "mcc": { "$ref": "#/components/schemas/mcc" }, "paymentFacilitator": { "$ref": "#/components/schemas/paymentFacilitator" }, "taxReference": { "$ref": "#/components/schemas/taxReference" } } }, "instruction": { "required": [ "value", "narrative", "paymentInstrument", "requestAutoSettlement" ], "type": "object", "description": "An object that contains all information related to the payment.", "properties": { "requestAutoSettlement": { "type": "object", "description": "Indicates whether the transaction should be sent for settlement now `true` or later `false`, at a time of your choosing.", "properties": { "enabled": { "type": "boolean" } } }, "value": { "allOf": [ { "$ref": "#/components/schemas/value" }, { "type": "object", "properties": { "estimated": { "type": "boolean", "description": "Set to `true` for an estimated authorization value, which you can [increase at a later stage](/products/card-payments/manage-payments#increase-an-authorization). {% admonition type=\"info\" name=\"Note\" %} `requestAutoSettlement` must be `false` for estimated authorizations.{% /admonition %} " }, "acceptPartialAmount": { "type": "boolean", "description": "Set to `true` to accept partial authorization amount. You can charge the remainder of the amount using a different payment credential with a new authorization request. {% admonition type=\"info\" name=\"Note\" %} `requestAutoSettlement` must be `false` for partial authorizations.{% /admonition %}" }, "surchargeAmount": { "type": "integer", "description": "The charging amount representing processing and service fees. Ensure that the `surchargeAmount` complies with local regulations and card network rules before applying. {% admonition type=\"info\" name=\"Note\" %} The surcharge fee is included in the total transaction amount, e.g. if the `value.surchargeAmount` is $20 and the `value.amount` is $100, then the actual cost of goods/services is $80. {% /admonition %}" }, "convenienceAmount": { "type": "integer", "description": "The charging amount representing the offer of a convenient payment method or channel (such as online booking fee). Ensure that the `convenienceAmount` complies with local regulations and card network rules before applying. {% admonition type=\"info\" name=\"Note\" %} The convenience fee is included in the total transaction amount, e.g. if the `value.convenienceAmount` is $20 and the `value.amount` is $100, then the actual cost of goods/services is $80. {% /admonition %}" } } } ] }, "narrative": { "$ref": "#/components/schemas/narrative" }, "paymentInstrument": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/card_plain" }, { "$ref": "#/components/schemas/card_token" }, { "$ref": "#/components/schemas/card_networkToken" }, { "$ref": "#/components/schemas/card_checkout" }, { "$ref": "#/components/schemas/card_wallet_applepay" }, { "$ref": "#/components/schemas/card_wallet_googlepay" }, { "$ref": "#/components/schemas/card_networkToken_applepay" }, { "$ref": "#/components/schemas/card_networkToken_googlepay" } ], "discriminator": { "mapping": { "card/plain": "#/components/schemas/card_plain", "card/token": "#/components/schemas/card_token", "card/networkToken": "#/components/schemas/card_networkToken", "card/checkout": "#/components/schemas/card_checkout", "card/wallet+applepay": "#/components/schemas/card_wallet_applepay", "card/wallet+googlepay": "#/components/schemas/card_wallet_googlepay", "card/networkToken+applepay": "#/components/schemas/card_networkToken_applepay", "card/networkToken+googlepay": "#/components/schemas/card_networkToken_googlepay" }, "propertyName": "type" } }, "customerAgreement": { "type": "object", "description": "Contains specific customer agreements for the transaction.", "oneOf": [ { "$ref": "#/components/schemas/cit_cardOnFile" }, { "$ref": "#/components/schemas/cit_subscription" }, { "$ref": "#/components/schemas/cit_installment" } ], "discriminator": { "propertyName": "type", "mapping": { "cardOnFile": "#/components/schemas/cit_cardOnFile", "subscription": "#/components/schemas/cit_subscription", "installment": "#/components/schemas/cit_installment" } } }, "consumerBillPayment": { "$ref": "#/components/schemas/consumerBillPayment" }, "debtRepayment": { "$ref": "#/components/schemas/debtRepayment" }, "requestAccountUpdater": { "$ref": "#/components/schemas/requestAccountUpdater" }, "fundsTransfer": { "$ref": "#/components/schemas/fundsTransfer" }, "routing": { "$ref": "#/components/schemas/routing" } } }, "riskProfile": { "type": "string", "description": "Used to apply the SCA exemption in the payment request and update the FraudSight data model to benefit future payments. \n\nIf using either the [FraudSight](/products/fraudsight/assessment#linking-the-fraudsight-assessment) or [Exemptions](/products/sca-exemptions/assessment#applying-the-exemption) API you __must__ provide this.\n", "example": "https://try.access.worldpay.com/riskProfile/{linkData}" }, "authentication": { "description": "An object containing authentication details.", "properties": { "threeDS": { "type": "object", "description": "3DS authentication data. Only allowed for `card/plain`, `card/token`, `card/checkout`, `card/networkToken` payment instruments.", "required": [ "version", "eci" ], "properties": { "version": { "maxLength": 10, "minLength": 5, "type": "string", "description": "The version of 3DS used to process the transaction.", "example": "2.2.0" }, "eci": { "maxLength": 2, "minLength": 2, "type": "string", "description": "Electronic Commerce Indicator (ECI).", "example": "05", "pattern": "^[0-9]{2}$" }, "authenticationValue": { "maxLength": 40, "minLength": 1, "type": "string", "description": "Required, if `authentication.eci` value is 01, 02, 05 or 06. A cryptographic value that provides evidence of the outcome of a 3DS verification.", "example": "kBNHXUAy4+HT1gAMBSDajheBcxQh" }, "transactionId": { "maxLength": 36, "minLength": 36, "type": "string", "description": "Required, if `authentication.eci` value is 01, 02, 05 or 06. A unique authentication transaction identifier, generated by the issuer.", "example": "b8fb4ecc-7e2e-4b1c-816d-0149849776b8", "format": "RFC 4122 UUID" }, "cryptogramAlgorithm": { "type": "integer", "description": "Indicates the algorithm used to generate the cryptogram. For Cartes Bancaires authorizations only.", "example": 2 }, "challengePreference": { "type": "string", "description": "Indicates the preferred challenge behavior. For Cartes Bancaires authorizations only. Must contain one of the following values.", "enum": [ "noPreference", "noChallengeRequested", "challengeRequested", "challengeMandated", "noChallengeRequestedTRAPerformed" ] }, "authenticationFlow": { "type": "string", "description": "Set to `challenge` if your customer was redirected to their bank to complete authentication, or `frictionless` if your customer completed authentication without needing to be redirected to their bank. For Cartes Bancaires authorizations only. Must contain one of the following values.", "enum": [ "challenge", "frictionless", "frictionlessDelegated" ] }, "status": { "type": "string", "description": "Indicates the outcome of the authentication or verification request.\n - `Y` - Successful authentication\n - `N` - Failed authentication\n - `U` - Unable to complete authentication\n - `A` - Successful attempts authentication\n - `I` - Exemption acknowledged\n\n For Cartes Bancaires authorizations only." }, "statusReason": { "type": "string", "description": "Provides further information relating to the outcome of the authentication. Returned for failed authentications only. For Cartes Bancaires authorizations only." }, "cancellationIndicator": { "type": "string", "description": "An indicator as to why the authentication was cancelled. For Cartes Bancaires authorizations only.", "minLength": 2, "maxLength": 2, "pattern": "^[0-9]{2}$", "example": "01" }, "networkScore": { "type": "string", "description": "The global score calculated by the Cartes Bancaires scoring platform. For Cartes Bancaires authorizations only.", "minLength": 1, "maxLength": 2, "pattern": "^[0-9]{1,2}$", "example": "7" }, "brand": { "type": "string", "description": "The card brand used in the authentication. For Cartes Bancaires authorizations only.", "enum": [ "cartesBancaires" ] } } }, "networkToken": { "type": "object", "description": "Network Token authentication. Only allowed for `card/networkToken` transactions.", "required": [ "cryptogram" ], "properties": { "cryptogram": { "type": "string", "minLength": 1, "maxLength": 40, "example": "BLIYQ4EA/wLF4/hK9ABFMAABAAA=", "description": "A payment specific value generated during authentication." }, "eci": { "maxLength": 2, "minLength": 2, "type": "string", "description": "Electronic Commerce Indicator (ECI).", "example": "05", "pattern": "^[0-9]{2}$" } } }, "customerData": { "type": "object", "description": "Additional customer details necessary to meet local authentication, as required by country-specific regulations. Currently, this object is used solely for domestic transactions in South Korea and applicable to `card/plain`, `card/token` and `card/checkout` instruments only.", "oneOf": [ { "$ref": "#/components/schemas/southKorea_personalAuth" }, { "$ref": "#/components/schemas/southKorea_corporateAuth" } ], "discriminator": { "mapping": { "southKorea/personal": "#/components/schemas/southKorea_personalAuth", "southKorea/corporate": "#/components/schemas/southKorea_corporateAuth" }, "propertyName": "type" } } } }, "exemption": { "$ref": "#/components/schemas/exemption" }, "shipping": { "$ref": "#/components/schemas/shipping" }, "order": { "$ref": "#/components/schemas/order" }, "recipient": { "$ref": "#/components/schemas/recipient" }, "customer": { "type": "object", "description": "Additional customer data.", "properties": { "documentReference": { "type": "string", "description": "Required for domestic processing in some Latin American countries.", "minLength": 1, "maxLength": 50, "pattern": "^[A-Za-z0-9_\\-\\/\\\\*~+.,&()]{1,50}$" }, "reference": { "type": "string", "description": "Merchant-generated customer reference.", "minLength": 1, "maxLength": 17, "pattern": "^[A-Za-z0-9 @!£*#$()\\+\\-_=.,/;:'\"]{1,17}$" }, "ipAddress": { "type": "string", "description": "Customer's IP address. Required for certain jurisdictions and/or MCCs.", "minLength": 1, "maxLength": 50, "pattern": "^[a-zA-Z0-9\\-:.]+$" }, "emailAddress": { "type": "string", "description": "Customer's email address. If enabled, your customer will receive the transaction outcome to this email address.", "minLength": 1, "maxLength": 128, "pattern": "^(?=(?:[^@]*@){1}[^@]*$)[\\x20-\\x7E]{1,128}$" } } }, "industryData": { "$ref": "#/components/schemas/industryData" } } } } } } ``` For more information about the accepted payment instruments, see our dedicated guidance: * [Worldpay tokens](https://developer.worldpay.com/products/tokens) * [Network tokens](#network-tokens) * [Checkout SDK](https://developer.worldpay.com/products/checkout) * [Mobile wallets](https://developer.worldpay.com/products/wallets) br ### Store a card If you are storing your customer's payment details for future use, you must indicate this using the `customerAgreement` object. Additionally, you can use our Tokens API to store your customer's card details via [Worldpay tokens](/products/tokens/create-a-token) or [network tokens](/products/tokens/create-a-network-token). Note **Important:** You must have consent from your customer to store their card details. You must also indicate when a card that you have stored previously is being used in a subsequent payment. **Example use cases:** - First card on file: a payment where the customer opts to store their card on your website for faster checkout on future purchases (i.e. express checkout). - Subsequent card on file: a payment where the customer selects a card that they have previously stored with you for an express checkout flow. - First payment in a subscription agreement. - First payment in an installment plan. Subsequent subscription or installment payments must be sent using our [merchant initiated transactions endpoint](/products/card-payments/repeat-payments), since these payments are not directly initiated by the cardholder. Note Strong Customer Authentication (SCA) is mandatory when storing payment details. You must include [3DS](#3ds) authentication or an [SCA Exemption](#sca-exemptions) when a stored card is being used for the first time. Example card on file requests: Card (first) ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/plain", "cardNumber": "4444333322221111", "expiryDate": { "month": 5, "year": 2035 }, "cvc": "123" }, "customerAgreement":{ "type": "cardOnFile", "storedCardUsage": "first" } }, "authentication": { "threeDS": { "eci": "05", "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAA3=", "transactionId": "a09b446d-5c0d-4003-9c99-21fb73d75999", "version": "2.2.0" } } } ``` Token (first) ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/token", "href": "https://try.access.worldpay.com/tokens/{}", "cvc": "123" }, "customerAgreement":{ "type": "cardOnFile", "storedCardUsage": "first" } }, "authentication": { "threeDS": { "eci": "05", "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAA3=", "transactionId": "a09b446d-5c0d-4003-9c99-21fb73d75999", "version": "2.2.0" } } } ``` Network token (first) ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/networkToken", "tokenNumber": "4444333322221111", "expiryDate": { "month": 5, "year": 2035 } }, "customerAgreement":{ "type": "cardOnFile", "storedCardUsage": "first" } }, "authentication": { "threeDS": { "eci": "05", "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAA3=", "transactionId": "a09b446d-5c0d-4003-9c99-21fb73d75999", "version": "2.2.0" }, "networkToken": { "cryptogram": "MAAAAAAAAAAAAAAAAAAAAAAAAAB=", "eci": "06" } } } ``` Card (subsequent) ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/plain", "cardNumber": "4444333322221111", "expiryDate": { "month": 5, "year": 2035 } }, "customerAgreement":{ "type": "cardOnFile", "storedCardUsage": "subsequent" } } } ``` Token (subsequent) ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/token", "href": "https://try.access.worldpay.com/tokens/{}", "cvc": "123" }, "customerAgreement":{ "type": "cardOnFile", "storedCardUsage": "subsequent" } } } ``` Network token (subsequent) ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/networkToken", "tokenNumber": "4444333322221111", "expiryDate": { "month": 5, "year": 2035 } }, "customerAgreement":{ "type": "cardOnFile", "storedCardUsage": "subsequent" } }, "authentication": { "networkToken": { "cryptogram": "MAAAAAAAAAAAAAAAAAAAAAAAAAB=", "eci": "05" } } } ``` Example first subscription requests: Card ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/plain", "cardNumber": "4444333322221111", "expiryDate": { "month": 5, "year": 2035 }, "cvc": "123" }, "customerAgreement":{ "type": "subscription", "storedCardUsage": "first" } }, "authentication": { "threeDS": { "eci": "05", "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAA3=", "transactionId": "a09b446d-5c0d-4003-9c99-21fb73d75999", "version": "2.2.0" } } } ``` Token ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/token", "href": "https://try.access.worldpay.com/tokens/{}", "cvc": "123" }, "customerAgreement":{ "type": "subscription", "storedCardUsage": "first" } }, "authentication": { "threeDS": { "eci": "05", "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAA3=", "transactionId": "a09b446d-5c0d-4003-9c99-21fb73d75999", "version": "2.2.0" } } } ``` Network token ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/networkToken", "tokenNumber": "4444333322221111", "expiryDate": { "month": 5, "year": 2035 } }, "customerAgreement":{ "type": "subscription", "storedCardUsage": "first" } }, "authentication": { "threeDS": { "eci": "05", "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAA3=", "transactionId": "a09b446d-5c0d-4003-9c99-21fb73d75999", "version": "2.2.0" }, "networkToken": { "cryptogram": "MAAAAAAAAAAAAAAAAAAAAAAAAAB=", "eci": "05" } } } ``` Apple Pay ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "customerAgreement": { "type": "subscription", "storedCardUsage": "first" }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/wallet+applepay", "walletToken": "{ \"version\": \"EC_v1\", \"data\": \"kdHd..GQ==\", \"signature\": \"MIAGCSqGSIb3DQEH...AAA\", \"header\": { \"transactionId\": \"d3b28af..f8\", \"ephemeralPublicKey\": \"MFkwE..Q==\", \"publicKeyHash\": \"dxCK..6o=\" } }" } } } ``` Google Pay ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "customerAgreement": { "type": "subscription", "storedCardUsage": "first" }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/wallet+googlepay", "walletToken": "{\"protocolVersion\":\"ECv1\",\"signature\":\"MEQCIH6Q4OwQ0jAceFEkGF0JID6sJNXxOEi4r+mA7biRxqBQAiAondqoUpU/bdsrAOpZIsrHQS9nwiiNwOrr24RyPeHA0Q\\u003d\\u003d\",\"signedMessage\":\"{\\\"tag\\\":\\\"jpGz1F1Bcoi/fCNxI9n7Qrsw7i7KHrGtTf3NrRclt+U\\\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"BJatyFvFPPD21l8/uLP46Ta1hsKHndf8Z+tAgk+DEPQgYTkhHy19cF3h/bXs0tWTmZtnNm+vlVrKbRU9K8+7cZs\\\\u003d\\\",\\\"encryptedMessage\\\":\\\"mKOoXwi8OavZ\\\"}\"}" } } } ``` Apple Pay decrypted ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/networkToken+applepay", "tokenNumber": "4444333322221111", "expiryDate": { "month": 5, "year": 2035 } }, "customerAgreement":{ "type": "subscription", "storedCardUsage": "first" } }, "authentication": { "networkToken": { "cryptogram": "MAAAAAAAAAAAAAAAAAAAAAAAAAB=", "eci": "05" } } } ``` Google Pay decrypted ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/networkToken+googlepay", "tokenNumber": "4444333322221111", "expiryDate": { "month": 5, "year": 2035 } }, "customerAgreement":{ "type": "subscription", "storedCardUsage": "first" } }, "authentication": { "networkToken": { "cryptogram": "MAAAAAAAAAAAAAAAAAAAAAAAAAB=", "eci": "05" } } } ``` | **Parameter** | **Required?** | **Description** | | --- | --- | --- | | `instruction.customerAgreement` | ❌ | An object containing details about processing agreements made with your customer, i.e.: An agreement to store the customer's paymentInstrument for future processing (e.g. set up a subscription plan or store a card on file)An agreement to set up an installment schedule (for Latin America payments) | | `customerAgreement.type` | ✅ | The processing arrangement agreed with your customer. Possible values:`cardOnFile` - for storing card details for future CITs`subscription` - for storing card details for a subscription agreement `installment` - for storing card details for an installment plan | | `customerAgreement.storedCardUsage` | Mandatory for types: `cardOnFile``subscription``installment` (where `installmentType` = `merchant` | Possible values:`first` - for storing a card for the first time`used` - for using a previously stored card | | `customerAgreement.installmentType` | Mandatory where `customerAgreement.type` = `installment` | Possible values:`merchant``latinAmerica` - for installment plans in Latin America | br ### Settlement #### Auto settlement You can request that payment authorizations are automatically sent for settlement (sometimes referred to as "capture") by setting `requestAutoSettlement.enabled` to `true` in your `/cardPayments/customerInitiatedTransactions` request. #### Manual settlement To manually request settlement at a time of your choosing, set `requestAutoSettlement.enabled` to `false`. You can then use the `cardPayments:settle` or `cardPayments:partialSettle` next action link returned in your response message to send the [full authorized amount](/products/card-payments/manage-payments#settle-an-authorization) or a [partial amount](/products/card-payments/manage-payments#partially-settle-an-authorization) for settlement. Note Payment Authorizations automatically expire after a set time period. The time period can be as little as three days, and depends on a number of parameters such as your region, Merchant Category Code (MCC), and the payment purpose. Please refer to card scheme documentation for the authorization expiry time periods for each scenario. br ### Network Tokens Network Tokens are format-preserving representations of a `cardNumber` (Primary Account Number, or PAN: the long card number, usually on the front of a card). This means that, like a `cardNumber`, network tokens are usually 16-digits in length. Some benefits of using network tokens: - Increased authorization rates - Reduced card scheme fees in some regions - Increased security given a new cryptogram must be provisioned for each customer initiated payment - Network tokens remain unaltered if the underlying card expires and is re-issued Note See our guidance on how to [Create a Network Token](https://developer.worldpay.com/products/tokens/create-a-network-token). When using network tokens in Customer Initiated Transactions, you must include the `cryptogram`. This can be obtained from our [Tokens API](/products/tokens/query-network-tokens-and-provision-cryptograms) or your Token provider. br Example network token requests: Network Token ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/networkToken", "tokenNumber": "4444333322221111", "expiryDate": { "month": 5, "year": 2035 } } }, "authentication": { "networkToken": { "cryptogram": "MAAAAAAAAAAAAAAAAAAAAAAAAAB=", "eci": "05" } } } ``` 3DS2 Network Token ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/networkToken", "tokenNumber": "4444333322221111", "expiryDate": { "month": 5, "year": 2035 } } }, "authentication": { "threeDS": { "eci": "05", "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAA3=", "transactionId": "a09b446d-5c0d-4003-9c99-21fb73d75999", "version": "2.2.0" }, "networkToken": { "cryptogram": "MAAAAAAAAAAAAAAAAAAAAAAAAAB=", "eci": "06" } } } ``` | **Parameter** | **Required** | **Description** | | --- | --- | --- | | `authentication.networkToken` | ✅ | An object containing network token verification details. | | `authentication.networkToken.cryptogram` | ✅ | The single-use cryptogram provisioned for this payment. | | `authentication.networkToken.eci` | ❌ | Electronic Commerce Indicator (ECI).Indicates the outcome of the network token verification.02 or 05 - Fully Authenticated Transaction01 or 06 - Attempted Authentication Transaction00 or 07 - Not successfully authenticated**Mastercard** - 02, 01, 00**Visa** - 05, 06, 07**Amex** - 05, 06, 07**JCB** - 05, 06, 07**Diners** - 05, 06, 07 | br ### FraudSight Linking the payment If using the [FraudSight API](/products/fraudsight) you must apply the `riskProfile` from the assessment response in the card payment request. This links the risk assessment to the payment and allows the data model to mature and identify future fraudulent transactions. See [linking the FraudSight assessment](/products/fraudsight/assessment#linking-the-fraudsight-assessment) for details. ``` "riskProfile": "https://try.access.worldpay.com/riskProfile/ewogICJ2IiA6IDEsC" ``` br ### SCA Exemptions #### Granted by Worldpay Apply your Worldpay granted exemption (from [Exemptions](/products/sca-exemptions/) or [FraudSight](/products/fraudsight/)) using the `riskProfile`. This allows the exemption to be applied to your payment authorization. ``` "riskProfile": "https://try.access.worldpay.com/riskProfile/ewogICJ2IiA6IDEsC" ``` br #### Granted by 3rd party TRA (external) To use exemptions granted by a 3rd party Transaction Risk Analysis (TRA) tool. This is not enabled by default, please contact your Worldpay Implementation Manager. Do not send externally granted TRA exemptions without approval from us and confirmation that we have fully enabled it. ```JSON "exemption": { "type": "external", "request": { "placement": "authentication", "type": "lowRisk" } } ``` br #### 3DS authentication outage exemption This is not enabled by default, please contact your Worldpay Implementation Manager. If 3DS suffers from a recognized downstream outage, you can apply an `authenticationOutage` exemption. Liability shift is not offered, but it increases the chance of an `authorized` outcome. ```JSON "exemption": { "type": "authenticationOutage" } ``` View the full exemption object schema ### 3DS Complete an [authentication request](/products/3ds/web/authentication) using our [3DS API](/products/3ds) to get the details required to prove that 3DS has taken place. 3DS2 Card ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/plain", "cardNumber": "4444333322221111", "expiryDate": { "month": 5, "year": 2035 } } }, "authentication": { "threeDS": { "eci": "05", "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAA3=", "transactionId": "a09b446d-5c0d-4003-9c99-21fb73d75999", "version": "2.2.0" } } } ``` 3DS2 Card (Cartes Bancaires) Cartes Bancaires requires some additional 3DS authentication details ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/plain", "cardNumber": "4444333322221111", "expiryDate": { "month": 5, "year": 2035 } } }, "authentication": { "threeDS": { "version": "2.1.0", "eci": "01", "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=", "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645", "cryptogramAlgorithm": 2, "challengePreference": "challengeMandated", "authenticationFlow": "challenge", "status": "Y", "statusReason": "11", "cancellationIndicator": "01", "networkScore": "00", "brand": "cartesBancaires" } } } ``` 3DS2 Token ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/token", "href": "https://try.access.worldpay.com/tokens/{}" } }, "authentication": { "threeDS": { "eci": "05", "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAA3=", "transactionId": "a09b446d-5c0d-4003-9c99-21fb73d75999", "version": "2.2.0" } } } ``` 3DS2 Network Token ```json { "transactionReference": "Memory265-13/08/1876", "channel": "ecom", "merchant": { "entity": "default" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "Mind Palace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/networkToken", "tokenNumber": "4444333322221111", "expiryDate": { "month": 5, "year": 2035 } } }, "authentication": { "threeDS": { "eci": "05", "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAA3=", "transactionId": "a09b446d-5c0d-4003-9c99-21fb73d75999", "version": "2.2.0" }, "networkToken": { "cryptogram": "MAAAAAAAAAAAAAAAAAAAAAAAAAB=", "eci": "06" } } } ``` Warning You cannot re-use the `authenticationValue` in multiple authorization requests. Re-using the `authenticationValue` will result in issuer declines and may incur fees. Note 3DS data cannot be supplied for MOTO transactions. | **Parameter** | **Required** | **Description** | | --- | --- | --- | | `authentication.threeDS` | ✅ | An object containing the result of your customer's verification. For more details see [3DS verification](/products/3ds/web/challenge-verification#verification). | | `authentication.threeDS.version` | ✅ | The version of 3DS used to process the transaction. Possible values for 3DS2: `2.1.0``2.2.0` Required for Mastercard's Identity Check transactions in Authorization. | | `authentication.threeDS.eci` | ✅ | Electronic Commerce Indicator (ECI).Indicates the outcome of the [3DS verification](/products/3ds/web/challenge-verification#verification).02 or 05 - Fully Authenticated Transaction01 or 06 - Attempted Authentication Transaction00 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.threeDS.authenticationValue` | ✅ | Required, if `threeDS.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)`threeDS.authenticationValue` must be 28 digits max and must be base64-encoded. | | `authentication.threeDS.transactionId` | ✅ | Required, if `threeDS.eci` value is 01, 02, 05 or 06.A unique authentication transaction identifier, generated by the issuer.For version 3DS2: `transactionId` follows RFC 4122 UUID standard and is 36 characters in length. | | `authentication.threeDS.cryptogramAlgorithm` | ❌ | Indicates the algorithm used to generate the cryptogram. For Cartes Bancaires authorizations only. | | `authentication.threeDS.challengePreference` | ❌ | Indicates the preferred challenge behavior.noPreferencenoChallengeRequestedchallengeRequestedchallengeMandatednoChallengeRequestedTRAPerformedFor Cartes Bancaires authorizations only. | | `authentication.threeDS.authenticationFlow` | ❌ | `challenge` - Your customer was redirected to their bank to complete authentication`frictionless` - Your customer completed authentication without needing to be redirected to their bankFor Cartes Bancaires authorizations only. | | `authentication.threeDS.status` | ❌ | Indicates the outcome of the authentication or verification request. `Y` - Successful authentication `N` - Failed authentication `U` - Unable to complete authentication `A` - Successful attempts authentication `I` - Exemption acknowledged For Cartes Bancaires authorizations only. | | `authentication.threeDS.statusReason` | ❌ | Provides further information relating to the outcome of the authentication. Returned for failed authentications only. For Cartes Bancaires authorizations only. | | `authentication.threeDS.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.threeDS.networkScore` | ❌ | The global score calculated by the Cartes Bancaires scoring platform.For Cartes Bancaires authorizations only. | | `authentication.threeDS.brand` | ❌ | The card brand used in the authentication.For Cartes Bancaires authorizations only. | br ### Enable additional features Account Updater Reduce declines and improve your customer's experience by automatically retrieving updated card details in real time. Co-branded Cards Take payments from cards that carry multiple card brands. Financial Services (MCC 6012/6051) Supply additional mandatory data if you offer financial services, debt repayments, or consumer bill payments. Funding Transactions (AFT) Take Account Funding Transactions (AFTs) to pull funds from a card account to another destination. Airline data Supply detailed airline itinerary data to achieve several cost and efficiency benefits. Corporate Purchasing Data (Level 2 / 3) Submit additional order, tax, and line item data in your payment authorization and settlement requests where your customer is using a commercial or purchasing card. Latin America Payments Take payments in Latin America, including regional installment plan options, combo cards, and supplying customer document references. MOTO transactions Take Mail Order/ Telephone Order payments. Partial authorizations Accept authorizations for partial amounts. View all features ## 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"` or `"Sent for Settlement"` * a `paymentId` - a unique identifier generated by us for a single payment. Generated at authorization, and maintained through successive payment actions * a `commandId` - a unique identifier generated by us for a single instance of an interaction (command) with our API * risk factors (only returned if issuer identifies conflict) * an [exemption result and reason](#exemptions) (only if you supplied a risk profile to request an [SCA exemption](/products/sca-exemptions)) * an issuer authorization code * links to either: * [settle](/products/card-payments/manage-payments#settle-an-authorization), [partially settle](/products/card-payments/manage-payments#partially-settle-an-authorization), [cancel](/products/card-payments/manage-payments#cancel-an-authorization), or [query a payment](/products/card-payments/query-a-payment) when `requestAutoSettlement` was set to `false` in the authorization request and the `outcome` is `"authorized"` * [refund](/products/card-payments/manage-payments#fully-refund-a-payment), [partially refund](/products/card-payments/manage-payments#partially-refund-a-payment), [reverse](/products/card-payments/manage-payments#reverse-a-payment) or [query a payment](/products/card-payments/query-a-payment) when `requestAutoSettlement` was set to `true` in the authorization request and the `outcome` is `"Sent for Settlement"` * a `paymentInstrument` object #### `paymentInstrument` We return the `"paymentInstrument"` object, if we are able to provide information related to the underlying card used in the authorization request. Note If we return the `paymentInstrument` object, there is no guarantee that each field listed below will be returned with every transaction. | Parameter | Description | | --- | --- | | `paymentInstrument.type` | The type of paymentInstrument. E.g.: `card/plain+masked``card/network+masked``card/network` | | `paymentInstrument.brand` | The card brand. Sometimes referred to as the network or scheme. E.g.: `visa``mastercard``amex` | | `paymentInstrument.cardBin` | The card bin. E.g.: `444433` this may contain the `*` character. | | `paymentInstrument.lastFour` | The last four digits of the card. E.g.: `1111` this may contain the `*` character, where the card number is less than 16 digits. | | `paymentInstrument.expiryDate.month` | The card expiry month. E.g.: `11` | | `paymentInstrument.expiryDate.year` | The card expiry year. E.g.: `2025` | | `paymentInstrument.fundingType` | How the card is funded. E.g.: `credit``debit``prepaid``deferredDebit``chargeCard` | | `paymentInstrument.category` | Whether the card is classed as a consumer card or a card for commercial use. E.g.: `consumer``commercial` | | `paymentInstrument.countryCode` | The alpha-2 ISO-3166 country code that the card was issued in. May return `"N/A"` where the country is unknown. E.g.: `GB` | | `paymentInstrument.issuerName` | The name of the card issuer. E.g.: `Some Issuer PLC.` | | `paymentInstrument.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 initiate a payment. E.g.: `ABC123DEF456GHI789JKL123MNO45` | | `paymentInstrument.debitNetwork` | The debit network that the transaction was routed through. Returned optionally for subscribing merchants. See our [API reference](/products/card-payments/openapi/other/authorize#other/authorize/t=response&c=201&path=&d=0/paymentinstrument/debitnetwork) for all possible values. | Marketplaces If you follow a Marketplace flow, ensure you **now** split your payment through our [Split Payments API](/products/split-payments/), to guarantee an automated payout to the party. ### Refused payment You receive: * an HTTP code `201` * an `"outcome": "refused"` * a `paymentId` - a unique identifier generated by us for a single payment. Generated at authorization, and maintained through successive payment actions * a `commandId` - a unique identifier generated by us for a single instance of an interaction (command) with our API * a `refusalCode` containing either our standard [refusal codes](/products/reference/refusal-response) or the [rawCode](/products/reference/refusal-response/scheme-codes) (if enabled) * a `refusalDescription` which gives additional context on the refusal * an [advice code](/products/reference/refusal-response#refusal-advice-codes) (only if returned by the card scheme and acquirer) * risk factors (only returned if issuer identifies conflict) * an [exemption result and reason](#exemptions) (only if you supplied a risk profile to request an [SCA exemption](/products/sca-exemptions)) * a `paymentInstrument` object ### Example response codeblock codeblockitem codeblockitem codeblockitem codeblockitem Card/Token ```json { "outcome": "authorized", "paymentId": "pay-fh47sbnaKR28AuocN28x0", "commandId": "cmdfHx982Nbhsklg91hsvlrv0", "riskFactors": [ { "type": "cvc", "risk": "notSupplied" }, { "type": "avs", "risk": "notChecked", "detail": "address" }, { "type": "avs", "risk": "notChecked", "detail": "postcode" } ], "issuer": { "authorizationCode": "12345A" }, "scheme": { "reference": "060720116005060" }, "paymentInstrument": { "type": "card/plain+masked", "cardBin": "444433", "lastFour": "1111", "category": "consumer", "expiryDate": { "month": 5, "year": 2035 }, "cardBrand": "visa", "fundingType": "credit", "issuerName": "Some Issuer PLC", "paymentAccountReference": "Q1HJZ28RKA1EBL470G9XYG90R5D3E" }, "_links": { "cardPayments:cancel": { "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazNhYjYzMiI=" }, "cardPayments:partialCancel": { "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/partials/eyJrIjoiazNhYjYzMiJ9" }, "cardPayments:settle": { "href": "https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazNhYjYzMiI=" }, "cardPayments:partialSettle": { "href": "https://try.access.worldpay.com/payments/settlements/partials/eyJrIjoiazNhYjYzMiI=" }, "cardPayments:events": { "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiI=" }, "curies": [ { "name": "cardPayments", "href": "https://try.access.worldpay.com/rels/cardPayments/{rel}", "templated": true } ] } } ``` Network Token ```json { "outcome": "authorized", "paymentId": "pay3N_87du2Sj-3HndV826xn0", "commandId": "cmdwZ5y_rSV1VmjD6CpgCuXG0", "riskFactors": [ { "type": "cvc", "risk": "notSupplied" }, { "type": "avs", "risk": "notMatched", "detail": "address" }, { "type": "avs", "risk": "notChecked", "detail": "postcode" } ], "issuer": { "authorizationCode": "12345A" }, "scheme": { "reference": "060720116005060" }, "paymentInstrument": { "type": "card/network", "cardBin": "444433", "expiryDate": { "month": 5, "year": 2035 }, "paymentAccountReference": "Q1HJZ28RKA1EBL470G9XYG90R5D3E" }, "_links": { "cardPayments:cancel": { "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazNhYjYzMiI" }, "cardPayments:partialCancel": { "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/partials/eyJrIjoiazNhYjYzMiJ9" }, "cardPayments:settle": { "href": "https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazNhYjYzMiI" }, "cardPayments:partialSettle": { "href": "https://try.access.worldpay.com/payments/settlements/partials/eyJrIjoiazNhYjYzMiI" }, "cardPayments:events": { "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiI" }, "curies": [ { "name": "cardPayments", "href": "https://try.access.worldpay.com/rels/cardPayments/{rel}", "templated": true } ] } } ``` Apple Pay/Google Pay ```json { "outcome": "authorized", "paymentId": "paygN28d-s18ncZnsDL02n470", "commandId": "cmdWP_h29znMbajSr2-911U70", "riskFactors": [ { "risk": "notChecked", "detail": "postcode", "type": "avs" }, { "risk": "notChecked", "detail": "address", "type": "avs" } ], "issuer": { "authorizationCode": "12345A" }, "scheme": { "reference": "060720116005060" }, "paymentInstrument": { "type": "card/network+masked", "cardBin": "444433", "lastFour": "1111", "tokenNumber": "444433******1111", "countryCode": "GB", "expiryDate": { "month": 2, "year": 2028 }, "cardBrand": "visa", "fundingType": "debit", "category": "consumer", "issuerName": "Some Issuer PLC", "paymentAccountReference": "Q1HJZ28RKA1EBL470G9XYG90R5D3E" }, "_links": { "cardPayments:cancel": { "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazUyOTVhMSIsImxpbmtWZXJzaW9uIjoiMy4wLjAifQ==.7uyuNo1ShOgM5rTwStg86LXzb0a2wdLW1lwX:DIQ2Ecrp4gw65VLnHmjsAVqzpa2NcwixaBb2p8R2x5NPXdRpybJ2ndKlbkNOc9gj+ruN20iaTdYqv2FNgB3ZAw3g+yyUMUlQDFD8DU++ZswXpUQe8YTBHmTP8zHQUXrSORn9IaI6kzJnMu2HWwEJOqKnWLvRCMy:fr4ptatJJrmRVON8WTjisJL:sd3TJ9uDcO:gD+q+Q01y++Mzop0k8y3bDcnNBpsG:8xf4uKGGYO3EcAWA==" }, "cardPayments:partialCancel": { "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/partials/eyJrIjoiazUyOTVhMSIsImxpbmtWZXJzaW9uIjoiMy4wLjAifQ==.7uyuNo1ShOgM5rTwStg86LXzb0a2wdLW1lwX:DIQ2Ecrp4gw65VLnHmjsAVqzpa2NcwixaBb2p8R2x5NPXdRpybJ2ndKlbkNOc9gj+ruN20iaTdYqv2FNgB3ZAw3g+yyUMUlQDFD8DU++ZswXpUQe8YTBHmTP8zHQUXrSORn9IaI6kzJnMu2HWwEJOqKnWLvRCMy:fr4ptatJJrmRVON8WTjisJL:sd3TJ9uDcO:gD+q+Q01y++Mzop0k8y3bDcnNBpsG:8xf4uKGGYO3EcAWA==" }, "cardPayments:settle": { "href": "https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazUyOTVhMSIsImxpbmtWZXJzaW9uIjoiMy4wLjAifQ==.7uyuNo1ShOgM5rTwStg86LXzb0a2wdLW1lwX:DIQ2Ecrp4gw65VLnHmjsAVqzpa2NcwixaBb2p8R2x5NPXdRpybJ2ndKlbkNOc9gj+ruN20iaTdYqv2FNgB3ZAw3g+yyUMUlQDFD8DU++ZswXpUQe8YTBHmTP8zHQUXrSORn9IaI6kzJnMu2HWwEJOqKnWLvRCMy:fr4ptatJJrmRVON8WTjisJL:sd3TJ9uDcO:gD+q+Q01y++Mzop0k8y3bDcnNBpsG:8xf4uKGGYO3EcAWA==" }, "cardPayments:partialSettle": { "href": "https://try.access.worldpay.com/payments/settlements/partials/eyJrIjoiazUyOTVhMSIsImxpbmtWZXJzaW9uIjoiMy4wLjAifQ==.7uyuNo1ShOgM5rTwStg86LXzb0a2wdLW1lwX:DIQ2Ecrp4gw65VLnHmjsAVqzpa2NcwixaBb2p8R2x5NPXdRpybJ2ndKlbkNOc9gj+ruN20iaTdYqv2FNgB3ZAw3g+yyUMUlQDFD8DU++ZswXpUQe8YTBHmTP8zHQUXrSORn9IaI6kzJnMu2HWwEJOqKnWLvRCMy:fr4ptatJJrmRVON8WTjisJL:sd3TJ9uDcO:gD+q+Q01y++Mzop0k8y3bDcnNBpsG:8xf4uKGGYO3EcAWA==" }, "cardPayments:events": { "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazUyOTVhMSIsImxpbmtWZXJzaW9uIjoiMy4wLjAifQ==.7uyuNo1ShOgM5rTwStg86LXzb0a2wdLW1lwX:DIQ2Ecrp4gw65VLnHmjsAVqzpa2NcwixaBb2p8R2x5NPXdRpybJ2ndKlbkNOc9gj+ruN20iaTdYqv2FNgB3ZAw3g+yyUMUlQDFD8DU++ZswXpUQe8YTBHmTP8zHQUXrSORn9IaI6kzJnMu2HWwEJOqKnWLvRCMy:fr4ptatJJrmRVON8WTjisJL:sd3TJ9uDcO:gD+q+Q01y++Mzop0k8y3bDcnNBpsG:8xf4uKGGYO3EcAWA==" }, "tokens:token": { "href": "https://access.worldpay.com/tokens/linkData" }, "curies": [{ "name": "cardPayments", "href": "https://try.access.worldpay.com/rels/payments/{rel}", "templated": true }] } } ``` Refusal ```json { "outcome": "refused", "paymentId": "pay29GnajUy2fBzC9552U_1b0", "commandId": "cmd9xmr5cSNtUulYlYW8kbY80", "refusalCode": "83", "refusalDescription": "Fraud/Security related reasons", "riskFactors": [ { "type": "riskProfile", "risk": "verificationFailed" }, { "type": "cvc", "risk": "notMatched" }, { "type": "avs", "risk": "notMatched", "detail": "address" }, { "type": "avs", "risk": "notChecked", "detail": "postcode" } ] } ``` Apple Pay/Google Pay Refusal ```json { "outcome": "refused", "paymentId": "pay38Ndh3N-cS18i023-hksO0", "commandId": "cmd93Ng8_KvnwI9sK7dJakl90", "description": "Do not honor", "refusalCode": "83", "refusalDescription": "Fraud/Security related reasons", "riskFactors": [ { "risk": "notChecked", "detail": "postcode", "type": "avs" }, { "risk": "notChecked", "detail": "address", "type": "avs" } ], "scheme": { "reference": "060720116005060" }, "paymentInstrument": { "type": "card/network+masked", "cardBin": "444433", "lastFour": "1111", "tokenNumber": "444433******1111", "countryCode": "GB", "expiryDate": { "month": 2, "year": 2028 }, "cardBrand": "visa", "fundingType": "debit", "category": "consumer", "issuerName": "Some Issuer PLC", "paymentAccountReference": "Q1HJZ28RKA1EBL470G9XYG90R5D3E" } } ``` Account Updater ```json { "outcome": "authorized", "paymentId": "pay28NdG68sv-13_sDcu5Bwt0", "commandId": "cmd8hJcb20_sh2-sbRjx88wL0", "riskFactors": [ { "type": "cvc", "risk": "notSupplied" }, { "type": "avs", "risk": "notChecked", "detail": "address" }, { "type": "avs", "risk": "notChecked", "detail": "postcode" } ], "issuer": { "authorizationCode": "12345A" }, "scheme": { "reference": "060720116005060" }, "updatedPaymentInstrument": { "cardBin": "491183", "lastFour": "0000", "expiryDate": { "month": 9, "year": 2031 }, "cardBrand": "visa", "fundingType": "credit", "accountUpdaterMessage": "The account number was changed", "type": "card/plain+masked" }, "paymentInstrument": { "type": "card/plain+masked", "cardBin": "444433", "lastFour": "1111", "category": "consumer", "expiryDate": { "month": 5, "year": 2023 }, "cardBrand": "visa", "fundingType": "credit", "issuerName": "Some Issuer PLC", "paymentAccountReference": "Q1HJZ28RKA1EBL470G9XYG90R5D3E" }, "_links": { "cardPayments:cancel": { "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazNhYjYzMiI=" }, "cardPayments:partialCancel": { "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/partials/eyJrIjoiazNhYjYzMiJ9" }, "cardPayments:settle": { "href": "https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazNhYjYzMiI=" }, "cardPayments:partialSettle": { "href": "https://try.access.worldpay.com/payments/settlements/partials/eyJrIjoiazNhYjYzMiI=" }, "cardPayments:events": { "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiI=" }, "curies": [ { "name": "cardPayments", "href": "https://try.access.worldpay.com/rels/cardPayments/{rel}", "templated": true } ] } } ``` You can use the `payments:settle` action link to [settle the payment](/products/card-payments/manage-payments#settle-an-authorization) straight away. You only receive this, if you set `"requestAutoSettlement"` to `false` in your initial request. Alternatively you can cache the response and use the link to settle the payment later. Note In case of an error, you can get further information in our [error reference](/products/reference/worldpay-error-responses). #### `riskFactors` To reduce the probability of processing a fraudulent payment, supply your customer's billing address and cvc in your [authorization request](#complete-authorization-request-schema). 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 `notChecked`, `notMatched`, `notSupplied` or `verificationFailed` | #### `exemptions` An [exemption](/products/sca-exemptions) result and reason if a [risk profile](/products/sca-exemptions/assessment#applying-the-exemption) 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 declines The issuer responds with a soft decline ([refusal code 65](/products/reference/refusal-response)), if no exemption has been applied to the payment. The next logical step for this is to proceed with [3DS authentication](/products/3ds/web/authentication). **Next steps** [Settle a payment](/products/card-payments/manage-payments#settle-an-authorization) [Refund a payment](/products/card-payments/manage-payments#fully-refund-an-authorization) [Cancel a payment](/products/card-payments/manage-payments#cancel-an-authorization) [Reverse a payment](/products/card-payments/manage-payments#reverse-an-authorization)