# Accept a payment using the Payments API You can use the Unified Payments API to request a payment with: - A [token](#Request_a_payment_with_a_token) - A [network token](#Request_a_payment_with_a_network_token) - A [payment instrument](#Request_a_payment_with_a_payment_instrument) - The [full card details](#Request_a_payment_with_full_card_details), if your level of [PCI compliance](https://www.checkout.com/docs/payments/ensure-regulatory-compliance/pci-compliance.md) is SAQ D ### Idempotency The Unified Payments API supports [idempotency](https://www.checkout.com/docs/developer-resources/api/idempotency.md). You can safely retry API requests without the risk of duplicate requests. ### Data quality You can provide additional payment and authentication data to [improve the data quality of your payment request](https://www.checkout.com/docs/payments/optimize-payments/improve-payment-request-data-quality.md). This can help issuers to identify fraudulent transactions and reduce false declines. ### Risk assessment The [Fraud Detection](https://www.checkout.com/docs/business-operations/prevent-fraud/understand-fraud-detection.md) solution uses the customer's IP address to assess the payment's risk. The `payment_ip` field supports IPv4 and IPv6 addresses. ### API responses For more information about payment request responses, see: - [API response codes](https://www.checkout.com/docs/resources/codes/api-response-codes.md) - [AVS codes](https://www.checkout.com/docs/resources/codes/avs-codes.md) - [CVV response codes](https://www.checkout.com/docs/resources/codes/cvv-response-codes.md) ### Webhooks To receive asynchronous status updates, you can call the [Get payment details](https://www.checkout.com/docs/payments/manage-payments/get-payment-details.md) endpoint, or [configure your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md). --- ## Get a list of available payment methods `Beta` To reduce the likelihood of declines due to unsupported payment methods, check which payment methods are configured on your account before you request a payment. You can use the values returned to ensure that you do not display unsupported payment methods to the customer at checkout. Call the [Get available payment methods](https://api-reference.checkout.com/tag/Payment-Methods/#operation/getPaymentMethods) endpoint, and provide the `processing_channel_id` as a query parameter. For example: ``` https://{prefix}.api.checkout.com/payment-methods?processing_channel_id=pc_ovo75iz4hdyudnx6tu74mum3fq ``` > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `GET` `https://{prefix}.api.checkout.com/payment-methods` **Sandbox** `GET` `https://{prefix}.api.sandbox.checkout.com/payment-methods` ### Response example ```json { "methods": [ { "type": "visa" }, { "type": "mastercard" }, { "type": "paypal", "partner_merchant_id": "XUDKCFT2RGRAC" }, { "type": "applepay" } ] } ``` --- ## Request a payment with a token A token is a secure representation of sensitive payment details. Requesting a payment with the token ensures that the details do not reach your server. You can [tokenize credentials with Flow](https://www.checkout.com/docs/payments/store-and-manage-credentials/tokenize-credentials.md) to receive a token when the customer submits their payment details on your checkout page. Call the [Request a payment or payout](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) endpoint and set the `source.type` field to `token`. > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/payments` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/payments` ### Request example ```json { "source": { "type": "token", "token": "tok_4gzeau5o2uqubbk6fufs3m7p54" }, "amount": 6500, "currency": "USD", "processing_channel_id": "pc_ovo75iz4hdyudnx6tu74mum3fq", "reference": "ORD-5023-4E89", "metadata": { "udf1": "TEST123", "coupon_code": "NY2024", "partner_id": 123989 } } ``` ### Response example **201 Success** ```json { "id": "pay_mbabizu24mvu3mela5njyhpit4", "action_id": "act_mbabizu24mvu3mela5njyhpit4", "amount": 6540, "currency": "USD", "approved": true, "status": "Authorized", "auth_code": "770687", "response_code": "10000", "response_summary": "Approved", "3ds": { "downgraded": true, "enrolled": "N" }, "risk": { "flagged": true }, "source": { "type": "card", "id": "src_nwd3m4in3hkuddfpjsaevunhdy", "billing_address": { "address_line1": "123 Anywhere St.", "address_line2": "Apt. 456", "city": "Anytown", "state": "AL", "zip": "123456", "country": "US" }, "phone": { "country_code": "+1", "number": "555 123 4567" }, "last4": "4242", "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832", "bin": "424242" }, "customer": { "id": "cus_udst2tfldj6upmye2reztkmm4i", "email": "ali.farid@example.com", "name": "Ali Farid" }, "processed_on": "2024-09-10T10:11:12Z", "reference": "ORD-5023-4E89", "processing": { "retrieval_reference_number": "909913440644", "acquirer_transaction_id": "440644309099499894406" }, "eci": "06", "scheme_id": "489341065491658", "links": { "self": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4" }, "action": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions" }, "void": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids" }, "capture": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures" } } } ``` **202 Payment asynchronous / further action required** ```json { "id": "pay_mbabizu24mvu3mela5njyhpit4", "status": "Pending", "reference": "ORD-5023-4E89", "customer": { "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44", "email": "ali.farid@example.com", "name": "Ali Farid" }, "3ds": { "downgraded": false, "enrolled": "Y" }, "instruction": { "value_date": "2024-08-25" }, "_links": { "self": { "href": "https://{prefix}.api.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4" }, "redirect": { "href": "https://{prefix}.api.checkout.com/3ds/pay_mbabizu24mvu3mela5njyhpit4" } } } ``` **422 Invalid data was sent** ```json { "request_id": "0HL80RJLS76I7", "error_type": "request_invalid", "error_codes": ["payment_source_required"] } ``` If you receive a `201` response with the following values, the authorization was successful: - `"approved": true` - `"status": "Authorized"` If you receive a `202` response, the payment requires a redirect. For example, if the payment was performed with [3D Secure (3DS)](https://www.checkout.com/docs/payments/authenticate-payments/3d-secure.md) authentication. The possible values for the `status` field are: - `Authorized` - `Pending` – 3DS payments that require a redirect can have `Pending` status while additional authentication is performed. - `Card Verified` - `Declined` – The authorization failed. The card used for the payment request may be invalid, expired, or have insufficient funds. --- ## Request a payment with a network token A [network token](https://www.checkout.com/docs/payments/store-and-manage-credentials/store-credentials/network-tokens.md) is a secure representation of a card's primary account number (PAN), provided by card networks. Call the [Request a payment or payout](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) endpoint and set the `source.type` field to `network_token`. > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/payments` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/payments` ### Request example ```json { "source": { "type": "network_token", "token": "4242424242424242", "token_type": "vts", "expiry_month": "10", "expiry_year": "2025", "eci": "06", "cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA=" }, "amount": 1000, "currency": "USD", "pan_preference": "dpan" } ``` ### Response example **201 Success** ```json { "id": "pay_mbabizu24mvu3mela5njyhpit4", "action_id": "act_mbabizu24mvu3mela5njyhpit4", "amount": 6540, "currency": "USD", "approved": true, "status": "Authorized", "auth_code": "770687", "response_code": "10000", "response_summary": "Approved", "3ds": { "downgraded": true, "enrolled": "N" }, "risk": { "flagged": true }, "source": { "type": "card", "id": "src_nwd3m4in3hkuddfpjsaevunhdy", "billing_address": { "address_line1": "123 Anywhere St.", "address_line2": "Apt. 456", "city": "Anytown", "state": "AL", "zip": "123456", "country": "US" }, "phone": { "country_code": "+1", "number": "555 123 4567" }, "last4": "4242", "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832", "bin": "424242" }, "customer": { "id": "cus_udst2tfldj6upmye2reztkmm4i", "email": "ali.farid@example.com", "name": "Ali Farid" }, "processed_on": "2024-09-10T10:11:12Z", "reference": "ORD-5023-4E89", "processing": { "retrieval_reference_number": "909913440644", "acquirer_transaction_id": "440644309099499894406", "pan_type_processed": "dpan", "cko_network_token_available": true }, "eci": "06", "scheme_id": "489341065491658", "links": { "self": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4" }, "action": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions" }, "void": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids" }, "capture": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures" } } } ``` **202 Payment asynchronous / further action required** ```json { "id": "pay_mbabizu24mvu3mela5njyhpit4", "status": "Pending", "reference": "ORD-5023-4E89", "customer": { "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44", "email": "ali.farid@example.com", "name": "Ali Farid" }, "3ds": { "downgraded": false, "enrolled": "Y" }, "instruction": { "value_date": "2024-08-25" }, "_links": { "self": { "href": "https://{prefix}.api.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4" }, "redirect": { "href": "https://{prefix}.api.checkout.com/3ds/pay_mbabizu24mvu3mela5njyhpit4" } } } ``` **422 Invalid data was sent** ```json { "request_id": "0HL80RJLS76I7", "error_type": "request_invalid", "error_codes": ["payment_source_required"] } ``` If you receive a `201` response with the following values, the authorization was successful: - `"approved": true` - `"status": "Authorized"` If you receive a `202` response, the payment requires a redirect. For example, if the payment was performed with 3DS authentication. The possible values for the `status` field are: - `Authorized` - `Pending` – 3DS payments that require a redirect can have `Pending` status while additional authentication is performed. - `Card Verified` - `Captured` - `Declined` – The authorization failed. The card used for the payment request may be invalid, expired, or have insufficient funds. - `Paid` ### Request a payment with a fallback card For third-party network tokens, you can improve payment performance and reliability by providing both a network token and a fallback card as alternative payment sources. This enables you to retry with the fallback card if the primary network token is declined. When you send both a digital PAN (DPAN) and a full PAN (FPAN) using the fallback functionality, you can include the `processing.pan_preference` field to determine which PAN Type is used on the first attempt. For information on how Checkout.com handles PAN fallback for network tokens managed by us, see [Full PAN fallback](https://www.checkout.com/docs/payments/store-and-manage-credentials/store-credentials/network-tokens.md#Full_PAN_fallback). Call the [Request a payment or payout](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) endpoint. In the request body, provide the following: - `source.type` field set to `network_token` - `fallback_source` object with the `type` field set to `card` and the card's full details. > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/payments` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/payments` #### Request example ```json { "source": { "type": "network_token", "token": "4500622868341387", "token_type": "vts", "expiry_month": "12", "expiry_year": "2029", "eci": "05", "cryptogram": "hv8mUFzPzRZoCAAAAAEQBDMAAAA=" }, "fallback_source": { "type": "card", "number": "4500622868300003", "expiry_month": "12", "expiry_year": "2029", "cvv": "123", "name": "Jia Tsang" }, "amount": 100, "currency": "EUR" } ``` #### Response example **201 Success – network token used** ```json { "id": "pay_sfy7igabmxgizmodfstqzv4jei", "action_id": "act_sfy7igabmxgizmodfstqzv4jei", "amount": 100, "currency": "EUR", "approved": true, "status": "Authorized", "auth_code": "770687", "response_code": "10000", "response_summary": "Approved", "source": { "type": "card", "id": "src_v3rde7z5rvie5j3nj6byb37n54", "expiry_month": 12, "expiry_year": 2029, "scheme": "Visa", "last4": "0003", "fingerprint": "CA8D03958F6098ADFA714BC83E6595448763E83A570EF028373A706C527943AB", "bin": "518574" }, "customer": { "id": "cus_udst2tfldj6upmye2reztkmm4i", "email": "jia.tsang@example.com", "name": "Jia Tsang" }, "processed_on": "2024-09-10T10:11:12Z", "processing": { "retrieval_reference_number": "909913440644", "acquirer_transaction_id": "440644309099499894406", "pan_type_processed": "dpan", "fallback_source_used": false }, "eci": "06", "scheme_id": "489341065491658", "_links": { "self": { "href": "https://{prefix}.api.checkout.com/payments/pay_sfy7igabmxgizmodfstqzv4jei" }, "actions": { "href": "https://{prefix}.api.checkout.com/payments/pay_sfy7igabmxgizmodfstqzv4jei/actions" }, "void": { "href": "https://{prefix}.api.checkout.com/payments/pay_sfy7igabmxgizmodfstqzv4jei/voids" }, "capture": { "href": "https://{prefix}.api.checkout.com/payments/pay_sfy7igabmxgizmodfstqzv4jei/captures" } } } ``` **201 Success – fallback source used** ```json { "id": "pay_r4bcxy29kqmewpnhj6tz7sd8fo", "action_id": "act_r4bcxy29kqmewpnhj6tz7sd8fo", "amount": 100, "currency": "EUR", "approved": true, "status": "Authorized", "auth_code": "770687", "response_code": "10000", "response_summary": "Approved", "source": { "type": "card", "id": "src_m8kpne5qvjcfzwl2th9xdra47y", "expiry_month": 12, "expiry_year": 2029, "scheme": "Visa", "last4": "0003", "fingerprint": "F639CAB2745BEE4140BF86DF6B6D6E3C8A1F527B9D04E2319C7A86F540123AB", "bin": "447447", "card_type": "CREDIT", "card_category": "CONSUMER", "issuer": "Test Bank", "issuer_country": "ES" }, "customer": { "id": "cus_r9kzvb8lq5mwphnx2czjydst4e", "email": "jia.tsang@example.com", "name": "Jia Tsang" }, "processed_on": "2024-09-10T10:11:12Z", "processing": { "retrieval_reference_number": "909913440644", "acquirer_transaction_id": "440644309099499894406", "pan_type_processed": "fpan", "fallback_source_used": true }, "eci": "06", "scheme_id": "489341065491658", "_links": { "self": { "href": "https://{prefix}.api.checkout.com/payments/pay_r4bcxy29kqmewpnhj6tz7sd8fo" }, "actions": { "href": "https://{prefix}.api.checkout.com/payments/pay_r4bcxy29kqmewpnhj6tz7sd8fo/actions" }, "void": { "href": "https://{prefix}.api.checkout.com/payments/pay_r4bcxy29kqmewpnhj6tz7sd8fo/voids" }, "capture": { "href": "https://{prefix}.api.checkout.com/payments/pay_r4bcxy29kqmewpnhj6tz7sd8fo/captures" } } } ``` The response includes the following fields that indicate which payment source was processed: - `processing.pan_type_processed` – The primary account number used to process the payment. - `dpan` – The network token was used. - `fpan` – The fallback card was used. - `processing.fallback_source_used` – Indicates whether the fallback card was used to complete the payment. When `false`, the primary network token was used. ### Test the fallback mechanism To test the fallback mechanism, send a payment request setting `source.token` to `4500622868341387`, and provide a valid card in the `fallback_source` object. #### Request example ```json { "source": { "type": "network_token", "expiry_month": "12", "expiry_year": "2029", "token": "4500622868341387", "token_type": "vts", "eci": "05", "cryptogram": "hv8mUFzPzRZoCAAAAAEQBDMAAAA=" }, "fallback_source": { "type": "card", "expiry_month": "12", "expiry_year": "2029", "number": "4500622868300003" } } ``` The response fails with a `20154` (3DS authentication required) response code. Checkout.com automatically retries the payment with the fallback card. --- ## Request a payment with a payment instrument A [payment instrument](https://www.checkout.com/docs/payments/store-and-manage-credentials/store-credentials/payment-instruments.md) is a secure representation of a customer's card or bank account that you have stored with Checkout.com for reuse. Call the [Request a payment or payout](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) endpoint and set the `source.type` field to `id`. > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/payments` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/payments` ### Request example ```json { "source": { "type": "id", "id": "src_wmlfc3zyhqzehihu7giusaaawu" }, "amount": 6500, "currency": "USD", "reference": "ORD-5023-4E89" } ``` ### Response example ```json { "id": "pay_mbabizu24mvu3mela5njyhpit4", "amount": 6500, "currency": "USD", "approved": true, "status": "Authorized", "auth_code": "770687", "response_code": "10000", "response_summary": "Approved", "source": { "type": "id", "id": "src_wmlfc3zyhqzehihu7giusaaawu" } } ``` --- ## Request a payment with full card details If your level of [PCI compliance](https://www.checkout.com/docs/payments/ensure-regulatory-compliance/pci-compliance.md) is SAQ D, you can request a payment using the card's full details. > **Information** > > To enable full card processing on your account, contact your solution engineer or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes). Call the [Request a payment or payout](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) endpoint and set the `source.type` field to `card`. > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/payments` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/payments` ### Request example ```json { "source": { "type": "card", "number": "4242424242424242", "expiry_month": 12, "expiry_year": 2022 }, "amount": 6500, "currency": "USD", "processing_channel_id": "processing_channel_id", "reference": "ORD-5023-4E89", "metadata": { "udf1": "TEST123", "coupon_code": "NY2024", "partner_id": 123989 } } ``` ### Response example **201 Success** ```json { "id": "pay_mbabizu24mvu3mela5njyhpit4", "action_id": "act_mbabizu24mvu3mela5njyhpit4", "amount": 6540, "currency": "USD", "approved": true, "status": "Authorized", "auth_code": "770687", "response_code": "10000", "response_summary": "Approved", "3ds": { "downgraded": true, "enrolled": "N" }, "risk": { "flagged": true }, "source": { "type": "card", "id": "src_nwd3m4in3hkuddfpjsaevunhdy", "billing_address": { "address_line1": "123 Anywhere St.", "address_line2": "Apt. 456", "city": "Anytown", "state": "AL", "zip": "123456", "country": "US" }, "phone": { "country_code": "+1", "number": "555 123 4567" }, "last4": "4242", "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832", "bin": "424242" }, "customer": { "id": "cus_udst2tfldj6upmye2reztkmm4i", "email": "ali.farid@example.com", "name": "Ali Farid" }, "processed_on": "2024-09-10T10:11:12Z", "reference": "ORD-5023-4E89", "processing": { "retrieval_reference_number": "909913440644", "acquirer_transaction_id": "440644309099499894406" }, "eci": "06", "scheme_id": "489341065491658", "links": { "self": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4" }, "action": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions" }, "void": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids" }, "capture": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures" } } } ``` **202 Payment asynchronous / further action required** ```json { "id": "pay_mbabizu24mvu3mela5njyhpit4", "status": "Pending", "reference": "ORD-5023-4E89", "customer": { "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44", "email": "ali.farid@example.com", "name": "Ali Farid" }, "3ds": { "downgraded": false, "enrolled": "Y" }, "instruction": { "value_date": "2024-08-25" }, "_links": { "self": { "href": "https://{prefix}.api.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4" }, "redirect": { "href": "https://{prefix}.api.checkout.com/3ds/pay_mbabizu24mvu3mela5njyhpit4" } } } ``` **422 Invalid data was sent** ```json { "request_id": "0HL80RJLS76I7", "error_type": "request_invalid", "error_codes": ["payment_source_required"] } ``` If you receive a `201` response with the following values, the authorization was successful: - `"approved": true` - `"status": "Authorized"` If you receive a `202` response, the payment requires a redirect. For example, if the payment was performed with 3DS authentication. The possible values for the `status` field are: - `Authorized` - `Pending` – 3DS payments that require a redirect can have `Pending` status while additional authentication is performed. - `Card Verified` - `Captured` - `Declined` – The authorization failed. The card used for the payment request may be invalid, expired, or have insufficient funds. - `Paid`