Menu

Take a payment

API v6
Last updated Nov 2021

To take a payment, you must first create anauthorization request. Your response contains links to your next available actions.


Authorize a payment

If you want to reserve funds in your customer's account, send us an authorization request.

POST your authorization request to thepayments:authorizeaction link received in yourquery the payments root resourcerequest to authorize a payment.

Authorization example request

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

The requests below contain all the mandatory fields needed for a successful authorization request. The full request schemas are available in ourAPI reference.

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

Authorization request body:

Copied!
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 5,
                "year": 2035
            }
        }
    }
}
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/token",
            "href": "https://try.access.worldpay.com/tokens/{}"
        }
    }
}
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "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=\" 
                }
            }"
        }
    }
}
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/wallet+googlepay",
            "walletToken": "{\"protocolVersion\":\"ECv2\",\"signature\":\"MEQCIH6Q4OwQ0jAceFEkGF0JID6sJNXxOEi4r+mA7biRxqBQAiAondqoUpU/bdsrAOpZIsrHQS9nwiiNwOrr24RyPeHA0Q\\u003d\\u003d\",\"intermediateSigningKey\":{\"signedKey\": \"{\\\"keyExpiration\\\":\\\"1542323393147\\\",\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/1+3HBVSbdv+j7NaArdgMyoSAM43yRydzqdg1TxodSzA96Dj4Mc1EiKroxxunavVIvdxGnJeFViTzFvzFRxyCw\\\\u003d\\\\u003d\\\"}\",\"signatures\": [\"MEYCIQCO2EIi48s8VTH+ilMEpoXLFfkxAwHjfPSCVED/QDSHmQIhALLJmrUlNAY8hDQRV/y1iKZGsWpeNmIP+z+tCQHQxP0v\"]},\"signedMessage\":\"{\\\"tag\\\":\\\"jpGz1F1Bcoi/fCNxI9n7Qrsw7i7KHrGtTf3NrRclt+U\\\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"BJatyFvFPPD21l8/uLP46Ta1hsKHndf8Z+tAgk+DEPQgYTkhHy19cF3h/bXs0tWTmZtnNm+vlVrKbRU9K8+7cZs\\\\u003d\\\",\\\"encryptedMessage\\\":\\\"mKOoXwi8OavZ\\\"}\"}"
        }
    }
}

Descriptions of your authorization request parameters

ParameterRequiredDescription
transactionReferenceA unique reference generated by you that is used to identify a payment throughout its lifecycle. Seetransaction reference format, for more details and the best practices.
merchantAn object that contains information about the merchant.
merchant.entityDirect your payment to assist with billing, reporting and reconciliation. This is mandatory for authentication and queries.
Contact yourImplementation Managerfor more details.
instructionAn object that contains all the information related to the payment.
instruction.narrativeThe text that appears on your customer's statement. Used to identify the merchant.
Seenarrative formatfor more details and best practices.
narrative.line1The 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.).
Seenarrative line1 formatfor more details.
instruction.valueAn object that contains information about the value of the payment.
value.currencyThe three digit currency code.
See list ofsupported currencies.
instruction.valueAn object that contains information about the value of the payment.
value.amountThe payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50. You can find the relevant exponent in ourcurrency table.
instruction.paymentInstrumentAn object that contains the payment type and details.
To use "tokens" as a paymentInstrument you must firstcreate a token.
paymentInstrument.cardExpiryDateAn object that contains your customer's card expiry date.
Mandatory for all "type": "card/plain" requests.
paymentInstrument.cardNumberAn object that contains your customer's card number. Mandatory for "type": "card/plain" requests.


3DS

3DS authorization request parameter descriptions

To get the customer authentication object you must complete anauthentication requestusing our3DS API.

Copied!
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 5,
                "year": 2035
            }
        }
    },
    "customer": {
        "authentication": {
            "version": "1.0.2",
            "type": "3DS",
            "eci": "05",
            "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
            "transactionId": "z9UKb06xLziZMOXBEmWSVA1kwG0="
        }
    }
}
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "trading name"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 5,
                "year": 2035
            }
        }
    },
    "customer": {
        "authentication": {
            "version": "2.1.0",
            "type": "3DS",
            "eci": "05",
            "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
            "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
        }
    }
}
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/token",
            "href": "https://try.access.worldpay.com/tokens/{}"
        }
    },
    "customer": {
        "authentication": {
            "version": "1.0.2",
            "type": "3DS",
            "eci": "05",
            "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
            "transactionId": "z9UKb06xLziZMOXBEmWSVA1kwG0="
        }
    }
}
{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/token",
            "href": "https://try.access.worldpay.com/tokens/{}"
        }
    },
    "customer": {
        "authentication": {
            "version": "2.1.0",
            "type": "3DS",
            "eci": "05",
            "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
            "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
        }
    }
}

The descriptions of parameters from your 3DS authorization request

ParameterRequiredDescription
customerAn object containing the result of your customer's verification. For more details see3DS verification.
authentication.type3DS
authentication.versionThe version of 3DS used to process the transaction.
For 3DS1 - 1.0.2
For 3DS2 - 2.1.0 or 2.2.0

Note: Required for Mastercard's Identity Check transactions in Authorization.

authentication.eciElectronic Commerce Indicator (ECI).
Indicates the outcome of the3DS verification.
  • 02 or 05 - Fully Authenticated Transaction
  • 01 or 06 - Attempted Authentication Transaction
  • 00 or 07 - Non 3-D Secure Transaction
  • Mastercard - 02, 01, 00
  • Visa - 05, 06, 07
  • Amex - 05, 06, 07
  • JCB - 05, 06, 07
  • Diners - 05, 06, 07
.
authentication.authenticationValueRequired, if authentication.eci value is 01, 02, 05 or 06.
A cryptographic value that provides evidence of the outcome of a 3DS verification.
  • Visa - Cardholder Authentication Verification Value (CAVV)
  • Mastercard - Universal Cardholder Authentication Field (UCAF)
authentication.authenticationValue must be 28 digits max and must be base64-encoded.
authentication.transactionIdRequired, if authentication.eci value is 01, 02, 05 or 06.
A unique authentication transaction identifier, generated by the issuer.

For version 3DS1: transactionId is base64-encoded and 28 digits in length.
For version 3DS2: transactionId follows RFC 4122 UUID standard and is 36 characters in length.

Optional fields in an authorization request

Check out ourAPI referencesfor more information on the Authorization request and schema for each version of our Payments API.

Response

Successful payment

You receive:

  • an HTTP code 201
  • an "outcome": "authorized"
  • risk factors (only returned if issuer identifies conflict)
  • an exemption result and reason (only if you provided a risk profile)
  • an issuer authorization code
  • links tocancel,settle,partially settleortrack payment events
  • a paymentInstrument (only for mobile wallet payments)

Refused payment

You receive:

  • an HTTP code 201
  • an "outcome": "refused"
  • arefusal code
  • a description which gives additional context on the refusal
  • risk factors (only returned if issuer identifies conflict)
  • an exemption result and reason (only if you provided a risk profile)
  • a paymentInstrument (only for mobile wallet payments)

Example response

Copied!
{
    "outcome": "authorized",
    "riskFactors": [{
            "risk": "not_matched",
            "type": "cvc"
        },
        {
            "risk": "not_checked",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "not_matched",
            "detail": "address",
            "type": "avs"
        }
    ],
    "exemption": {
        "result": "honored",
        "reason": "issuerHonored"
    },
    "issuer": {
        "authorizationCode": "0"
    },
    "_links": {
        "payments:cancel": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:settle": {
            "href": "https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:partialSettle": {
            "href": "https://try.access.worldpay.com/payments/settlements/partials/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:events": {
            "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiJ9"
        },
        "curies": [{
            "name": "payments",
            "href": "https://try.access.worldpay.com/rels/payments/{rel}",
            "templated": true
        }]
    }
}
{
    "outcome": "authorized",
    "riskFactors": [{
        "risk": "not_checked",
        "detail": "postcode",
        "type": "avs"
    },
    {
        "risk": "not_matched",
        "detail": "address",
        "type": "avs"
    }],
    "paymentInstrument": {
        "type": "card/network+masked",
        "card": {
            "number": {
                "bin": "444433",
                "last4Digits": "1111"
            },
            "countryCode": "GB",
            "expiryDate": {
                "month": 1,
                "year": 2020
            },
            "brand": "visa",
            "fundingType": "debit",
            "issuer": {
                "name": "VALID_ISSUER"
            },
            "paymentAccountReference": "somePAR"
        }
    },
    "_links": {
        "payments:cancel": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:settle": {
            "href": "https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:partialSettle": {
            "href": "https://try.access.worldpay.com/payments/settlements/partials/eyJrIjoiazNhYjYzMiJ9"
        },
        "payments:events": {
            "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiJ9"
        },
        "curies": [{
            "name": "payments",
            "href": "https://try.access.worldpay.com/rels/payments/{rel}",
            "templated": true
        }]
    }
}
{
    "outcome": "refused",
    "description": "CARD EXPIRED",
    "code": "33",
    "riskFactors": [{
            "risk": "not_supplied",
            "type": "cvc"
        },
        {
            "risk": "not_checked",
            "detail": "address",
            "type": "avs"
        },
        {
            "risk": "not_checked",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "verificationFailed",
            "type": "riskProfile"
        }
    ]
}
{
    "outcome": "refused",
    "description": "Do not honour",
    "code": "5",
    "riskFactors": [{
        "risk": "not_checked",
        "detail": "postcode",
        "type": "avs"
    },
    {
        "risk": "not_matched",
        "detail": "address",
        "type": "avs"
    }],
    "paymentInstrument": {
        "type": "card/network+masked",
        "card": {
            "number": {
                "bin": "444433",
                "last4Digits": "1111"
            },
            "countryCode": "GB",
            "brand": "visa",
            "fundingType": "debit",
            "issuer": {
                "name": "VALID_ISSUER"
            },
            "paymentAccountReference": "somePAR"
        }
    }
}

You can use thepayments:settleaction link tosettle the paymentstraight away. 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 ourerror reference.


riskFactors

exemption

Soft decline

The issuer responds with a soft decline (refusal code 65), if no exemption has been applied to the payment. The next logical step for this is to proceed with3DS authentication.

Next steps


Settle or cancel a payment