Card Tokens API

The Card Tokens API turns card details into a card token that you can charge. It has one operation:

Create Card Token (POST /client/v1/card-tokens): exchange card details for a token id.

This endpoint is under the /client prefix, which means it is built to be called from the shopper’s browser or app with your publishable key. For request and response shapes, see the Card Tokens API Specification. For why tokenization matters and how the whole flow fits together, see Card Tokenization.

Create a card token

Authenticate with your merchant ID and your publishable key, not your API key. See Authentication.


POST https://api.beamcheckout.com/client/v1/card-tokens
Content-Type: application/json
Authorization: Basic <base64(merchantId:publishableKey)>
 
{
  "cardHolderName": "CARDHOLDER NAME",
  "expiryMonth": 12,
  "expiryYear": 30,
  "pan": "4111111111111111"
}

Field	Required	Notes
`pan`	Yes	The card number.
`expiryMonth`	Yes	The expiry month, for example `12`.
`expiryYear`	Yes	The expiry year, for example `30`.
`cardHolderName`	No	Up to 100 characters.

The response is the token id:


{
  "id": "exampleCardTokenId"
}

Important

Send this request from your client, not from your server. Routing it through your server puts the raw card number in your systems, which is exactly what tokenization is meant to avoid.

Charge a card token

Pass the token id to POST /api/v1/charges with paymentMethodType CARD_TOKEN, authenticating with your API key this time:


POST https://api.beamcheckout.com/api/v1/charges
Content-Type: application/json
Authorization: Basic <base64(merchantId:apiKey)>
 
{
  "amount": 10000,
  "currency": "THB",
  "paymentMethod": {
    "cardToken": {
      "cardTokenId": "exampleCardTokenId",
      "securityCode": "123"
    },
    "paymentMethodType": "CARD_TOKEN"
  },
  "referenceId": "order_190821",
  "returnUrl": "https://www.beamcheckout.com"
}

From here the charge behaves like any other card charge. Handle actionRequired, then wait for the charge.succeeded webhook. See Charges API.

For installments on a stored card, use CARD_TOKEN_INSTALLMENTS. For the exact request shape of each payment method, see CreateChargeRequest.

Errors

See Error Handling. A 401 with INVALID_CREDENTIALS_ERROR on this endpoint usually means an API key was sent where the publishable key belongs, or the other way round.