Once you've successfully set up your integration, you're able to start receiving and tokenizing your customers' card details. After this tokenization process, you're ready to create a payment. To do this, you can use our API and your server-side code.

How it works

Card tokens (tok_) are single use and only have a 15-minute lifespan. Once you've successfully sent your request, you'll receive a response containing a permanent card source ID (src_) which can be used in subsequent payment requests.

Request a card payment

The POST request

Use the details below to set up your request.

Endpoint

POSThttps://api.checkout.com/payments

POSThttps://api.sandbox.checkout.com/payments

Header parameters

Header Value

Authorization

REQUIRED

secret key

_{Use the valid secret key of your Checkout.com account. You can find this in the Hub.}

Content-Type

REQUIRED

application/json

Body parameters

The table below describes the minimum recommended fields. For the full API specification, see the API reference.

Field name	Description
`source` OBJECT REQUIRED	Details about the payment source.
`source.type` STRING REQUIRED	The type of payment source. Set this to `token`.
`source.token` STRING REQUIRED	The Checkout.com token. This could be for a card, wallet, or alternative payment method.
`amount` INTEGER OPTIONAL	The payment amount in your chosen currency. Omit the amount or provide a value of `0` to perform a card verification. _{The format depends on the currency. For more information, see Calculating the value.}
`currency` STRING REQUIRED	A three-letter ISO currency code representing the currency of the payment.
`reference` STRING OPTIONAL	An optional reference you can use to identify the payment later. For example, an order number. _{If using Bambora as a third-party acquirer, this field is numeric only and limited to 12 characters maximum.}
`metadata` OBJECT OPTIONAL	Allows you to store additional information about a transaction (e.g., a coupon code) with custom fields and up to five user-defined fields (`udf1` to `udf5`), which can be used for reporting purposes. _{udf1 is also used for some of our risk rules.}

IPv4 or IPv6 addresses?

The optional payment_ip field, which is used by our risk engine to check the customer's IP address, only accepts IPv4 addresses.

Request example

{
  "source": {
    "type": "token",
    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
  },
  "amount": 6500,
  "currency": "USD",
  "reference": "ORD-5023-4E89",
  "metadata": {
    "udf1": "TEST123",
    "coupon_code": "NY2018",
    "partner_id": 123989
  }
}

The POST response

Use the approved field to check whether or not the authorization was successful ("approved": true). If your authorization was not successful, it's possible the payment used an invalid/expired card, or a valid card with an insufficient available balance.

If you received a 202 response, the payment requires a redirect. For example, if the payment is 3D Secure.

The following pages can help you understand the response message:

CVV codes and descriptions
AVS codes
Response codes (if the authorization was unsuccessful)

Response example

The possible values for the status field include Authorized, Captured, Card Verified, Declined, and Pending. Note that Pending only applies to 3D Secure payments and alternative payments.

{
  "id": "pay_mbabizu24mvu3mela5njyhpit4",
  "action_id": "act_mbabizu24mvu3mela5njyhpit4",
  "amount": 6500,
  "currency": "USD",
  "approved": true,
  "status": "Authorized",
  "auth_code": "770687",
  "eci": "05",
  "scheme_id": "638284745624527",
  "response_code": "10000",
  "response_summary": "Approved",
  "risk": {
    "flagged": false
  },
  "source": {
    "id": "src_nwd3m4in3hkuddfpjsaevunhdy",
    "type": "card",
    "expiry_month": 9,
    "expiry_year": 2022,
    "scheme": "Visa",
    "last4": "4242",
    "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832",
    "bin": "424242",
    "card_type": "Credit",
    "card_category": "Consumer",
    "issuer": "JPMORGAN CHASE BANK NA",
    "issuer_country": "US",
    "product_id": "A",
    "product_type": "Visa Traditional",
    "avs_check": "S",
    "cvv_check": ""
  },
  "customer": {
    "id": "cus_udst2tfldj6upmye2reztkmm4i"
  },
  "processed_on": "2019-01-25T11:03:36Z",
  "reference": "ORD-5023-4E89",
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
    },
    "actions": {
      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
    },
    "capture": {
      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
    },
    "void": {
      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
    }
  }
}

{
  "id": "pay_y3oqhf46pyzuxjbcn2giaqnb44",
  "status": "Pending",
  "reference": "ORD-5023-4E89",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "email": "sarah.mitchell@checkout.com",
    "name": "Sarah Mitchell"
  },
  "3ds": {
    "downgraded": false,
    "enrolled": "Y"
  },
  "_links": {
    "self": {
      "href": "https://api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
    },
    "redirect": {
      "href": "https://api.checkout.com/3ds/pay_y3oqhf46pyzuxjbcn2giaqnb44"
    }
  }
}

{
  "request_id": "0HL80RJLS76I7",
  "error_type": "request_invalid",
  "error_codes": [
    "payment_source_required"
  ]
}

Possibly fraudulent authorization requests return the message risk.flagged: true to show that the payment has been flagged.

Next step

Once you've successfully processed a card payment request, you're able to easily reuse those card details for subsequent payments.

Can we help?

Thanks for using Checkout.com. If you need help or have a question, message our Support team at support@checkout.com.

Powered by Atlassian Confluence and Scroll Viewport.