Use an existing card

There's no need to request your customers’ card details for every payment. Instead, you can use a source ID to securely process their subsequent payments without having to re-enter their card number. It's simple, fast, and secure!

After your customer makes an initial order, we securely store the card information and return to you a source identifier (id). This unique ID replaces the card number in all future payments, removing the need to exchange sensitive payment information.

The request

Use the details below to set up your request.

Endpoints

Live

POSThttps://api.checkout.com/payments

Sandbox

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

Header parameters

Header parameter	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` String required	Details about the payment source.
`source.type`\ String\ required	The type of payment source. Set this to `id`.
`source.id`\ String\ required	The source ID (prefixed by `src_`).
`source.cvv`\ String\ optional	The card verification value/code.\ 3 digits, except for Amex which is 4.
`amount`\ integer \ optional	The payment amount.\ Omit the amount or provide a value of `0` to perform a card verification.
`currency`\ String\ required	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.

Request example

{
  "source": {
    "type": "id",
    "id": "src_aj4isch2q2lujekf2o4cenzrpe",
    "cvv": 100
  },
  "amount": 6000,
  "currency": "USD",
  "reference": "ORD-5023-4E89"
}

The 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 made with 3D Secure (3DS) authentication

Response example

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

{
  "id": "pay_zpg25obbkv2uld22vto2zy5b3m",
  "action_id": "act_zpg25obbkv2uld22vto2zy5b3m",
  "amount": 6000,
  "currency": "USD",
  "approved": true,
  "status": "Authorized",
  "auth_code": "876545",
  "eci": "05",
  "scheme_id": "638284745624527",
  "response_code": "10000",
  "response_summary": "Approved",
  "risk": {
    "flagged": false
  },
  "source": {
    "id": "src_aj4isch2q2lujekf2o4cenzrpe",
    "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": "Y"
  },
  "customer": {
    "id": "cus_hafan7x5nfru7fpcs3yto645si"
  },
  "processed_on": "2019-01-25T10:42:20Z",
  "reference": "ORD-5023-4E89",
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_zpg25obbkv2uld22vto2zy5b3m"
    },
    "actions": {
      "href": "https://api.sandbox.checkout.com/payments/pay_zpg25obbkv2uld22vto2zy5b3m/actions"
    },
    "capture": {
      "href": "https://api.sandbox.checkout.com/payments/pay_zpg25obbkv2uld22vto2zy5b3m/captures"
    },
    "void": {
      "href": "https://api.sandbox.checkout.com/payments/pay_zpg25obbkv2uld22vto2zy5b3m/voids"
    }
  }
}

{
  "id": "pay_y3oqhf46pyzuxjbcn2giaqnb44",
  "status": "Pending",
  "reference": "ORD-5023-4E89",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "email": "[email protected]",
    "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"
  ]
}

Can we help?

Thanks for using Checkout.com. If you need any help or support, then message our support team at [email protected].