Card Authorization API

This section will walk you through the card authorization APIs to complete your authorization, including

• Create Card Authorization to initiate an authorization
• Get Card Authorization to inquire the status of the authorization
• List Card Authorizations to list historical authorizations
• Webhooks to get notified of authorization status changes

You can see the API reference at Card Authorization API Specification, and a full detailed example at Card Authorization Integration Guide.

Creating Card Authorizations via API

Beam supports authorization via POST /api/v1/card-authorizations. This flow allows for a full customization of your payment experience and requires you to build your own interface for checkout.

Currently, card authorizations do not support multiple captures.

The following payment methods are supported on the Beam Card Authorization API:

• Card (CARD)
• Card Token (CARD_TOKEN)

Example Card Authorization Creation Requests

Card Authorization

POST https://api.beamcheckout.com/api/v1/card-authorizations
Content-Type: application/json
Authorization: Basic {{yourMerchantId}} {{yourApiKey}}
 
{
  "currency": "THB",
  "amount": 10000,
  "referenceId": "order_190821",
  "returnUrl": "https://www.beamcheckout.com",
  "paymentMethod": {
    "paymentMethodType": "CARD",
    "card": {
      "pan": "4111111111111111",
      "cardHolderName": "CARDHOLDER NAME",
      "expiryMonth": 12,
      "expiryYear": 30,
      "securityCode": "123"
    },
  },
  "skip3dsFlow": false
}

If your merchant account has been set up to allow bypass 3DS authentication flow, you can set skip3dsFlow to true.

Handling Card Authorization Creation Response

Once an API call is made successfully, a card authorization is created. However, some card authorizations may require additional steps to complete the payment. This is indicated in the actionRequired field of the creation response. There are 2 possible values for this field:

• NONE: No additional action is required to complete the payment.
• REDIRECT: The shopper needs to be redirected to a URL to complete. This is shown in the redirect object of the response.

Here are examples of all the possible responses for a card authorization creation:

No Action Required

{
  "actionRequired": "NONE",
  "chargeId": "ca_2xTsz7Qit55pahSvKfJG3UMkpFQ",
  "paymentMethodType": "CARD"
}

Redirect Required

{
  "actionRequired": "REDIRECT",
  "cardAuthorizationId": "ca_2xTsz7Qit55pahSvKfJG3UMkpFQ",
  "redirect": {
    "redirectUrl": "https://www.beamcheckout.com/redirect"
  },
  "paymentMethodType": "CARD"
}

Here is an example diagram showing the usage of the Card Authorizations API to create a card authorization with a client-server architecture:

1. The shopper initiates an action on the merchant’s client that requires authorization.

2. Merchant’s client makes a request to the merchant’s server.

3. Merchant’s server makes a request to Beam to initiate the authorization.

4. Beam creates the card authorization with PENDING status.

5. Beam returns a response to the merchant’s server, which can be either a REDIRECT (requiring further shopper action) or NONE (no further action needed).

6. (REDIRECT flow) The merchant’s server returns the redirect URL to the merchant’s client.

7. (REDIRECT flow) The merchant’s client redirects the shopper to the provided URL.

8. (REDIRECT flow) The shopper completes the authorization process on the redirected page.

9. Following a successful authorization (either after step 8 in a REDIRECT flow or after step 5 in a NONE flow), Beam updates the card authorization status to SUCCEEDED.

10. Beam sends a webhook to the merchant’s server to provide a status update on the authorization.

11. The merchant’s server processes the event and acknowledges the webhook, completing the flow.

Get Card Authorization via API

You can retrieve the details of a specific card authorization using the cardAuthorizationId obtained from the card authorization creation response by calling the Get Card Authorization API ( GET /api/v1/card-authorizations/{cardAuthorizationId}).

List Card Authorizations via API

You can use the List Card Authorizations API (GET /api/v1/card-authorizations) to list all card authorizations created under your merchant account. You can also use query parameters to filter the results based on criteria such as referenceId specified upon card authorization creation.

Listening to Card Authorization Webhooks

You can configure your webhook endpoint to listen to card authorization related events, such as card_authorizations.succeeded by following instructions in the Webhook guide.

What’s Next?

After the status of your card authorization becomes AUTHORIZED from creating and handling it as described above, you can proceed to either:

• Capture up to the authorized amount using the Capture API
• Cancel the authorization using the Cancel API