Guides
API Reference

Our reference library for integrating with our API

FAQ

Find answers to our most frequently asked questions

Classic Docs

Documentation for our Classic API

Account Funding Transactions

The Unified Payments API can be used to perform Account Funding Transactions (AFTs). AFTs are a type of pull payment used primarily to fund a wallet.

We support AFTs for pull payments using both Mastercard and Visa cards.

To start using this feature, please contact your Customer Success manager.

The request

Use the details below to set up your request.

Endpoints

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

Header parameters

HeaderValue

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.

Field nameDescription

source

REQUIRED

OBJECT

Details about the payment source.

source.type

REQUIRED

STRING

The type of payment source. Set this to token.

source.token

REQUIRED

STRING

The Checkout.com token.

amount

OPTIONAL

INTEGER

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

REQUIRED

STRING

A three-letter ISO currency code representing the currency of the payment.

processing

OPTIONAL

OBJECT

Details about the processing.

processing.aft

OPTIONAL

BOOLEAN

Indicates whether the payment is an Account Funding Transaction (AFT).

recipient

OPTIONAL

OBJECT

Details about the recipient.

recipient.first_name

REQUIRED for Mastercard

OPTIONAL for Visa

STRING

The first name of the recipient of the funds.

recipient.last_name

REQUIRED for Mastercard

OPTIONAL for Visa

STRING

The last name of the recipient of the funds.

recipient.account_number

REQUIRED for Mastercard

OPTIONAL for Visa

STRING

The primary account number (PAN) of the recipient's account.

recipient.country

OPTIONAL

STRING

The country (two-letter ISO country code) of the recipient's address.

Required for Mastercard when the domestic funding transaction is used to fund a subsequent cross-border funds transfer.

Request example

{	
  "source": {
    "type": "token",
    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54",
  },
  "amount": 100,
  "currency": "USD",
  "processing": {
    "aft": true,
  },
  "recipient": {
    "first_name": "John",
    "last_name": "Smith",
    "account_number": "5555555555554444",
    "country": "GB"
  }
}

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 3D Secure.

The following pages can help you understand the response message:

Response example

The possible values for the status field include AuthorizedCapturedCard VerifiedDeclined, and Pending. Note that Pending only applies to 3D Secure 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"
    }
  }
}

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