Implement Credit Card Checkout (API)

Fetch a session key
This creates a JWT token for the customer, and authorizes the user to call these endpoints. You will pass the returned session key as x-coinflow-auth-session-key header.

Note: x-coinflow-auth-user-id can be thought of as a unique customer id that you use/define on your systems.

Request

1 curl --request GET \
2      --url https://api-sandbox.coinflow.cash/api/auth/session-key \
3      --header 'Authorization: YOUR_API_KEY' \
4      --header 'accept: application/json' \
5      --header 'x-coinflow-auth-user-id: customer123' // This is a merchant defined customer id. Can be any string the merchant uses to identify the purchaser.

Response

{
  "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiY3VzdG9tZXIxMjMiLCJtZXJjaGFudElkIjoidHlsZWUiLCJpYXQiOjE3MzQzNjY4NDksImV4cCI6MTczNDQ1MzI0OX0.rxyzFgSZNtIR7KguHyb7MFq2xeDNKH2-3NA49eHH-7Y"
}

Get the Totals for the checkout to show the customer a quote inclusive of all fees.

Request

1 curl --request POST \
2      --url https://api-sandbox.coinflow.cash/api/checkout/totals/merchantId \
3      --header 'accept: application/json' \
4      --header 'content-type: application/json' \
5      --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiY3VzdG9tZXIxMjMiLCJtZXJjaGFudElkIjoidHlsZWUiLCJpYXQiOjE3MzQzNjY4NDksImV4cCI6MTczNDQ1MzI0OX0.rxyzFgSZNtIR7KguHyb7MFq2xeDNKH2-3NA49eHH-7Y' \
6      --data '
7 {
8   "subtotal": {
9     "cents": 100
10   },
11   "settlementType": "USDC"
12 }
13 '

Response

{
  "card": {
    "subtotal": {
      "cents": 100
    },
    "creditCardFees": {
      "cents": 40
    },
    "chargebackProtectionFees": {
      "cents": 0
    },
    "gasFees": {
      "cents": 0
    },
    "total": {
      "cents": 140
    }
  },
  "ach": {
    "subtotal": {
      "cents": 100
    },
    "creditCardFees": {
      "cents": 100
    },
    "chargebackProtectionFees": {
      "cents": 0
    },
    "gasFees": {
      "cents": 0
    },
    "total": {
      "cents": 200
    }
  }
}

Enable a New Card Checkout This endpoint will enable a new user who has never made a purchase to complete their purchase with a credit card.

🚧 You MUST Complete the following before calling New Card Checkout:

✅ Implement Card Tokenization with Coinflow’s Card Form UI. This ensures PCI Compliance on all payments and is required for implementation. Follow the below recipe to learn how to tokenize a credit card. See tab: Tokenize New Card

PCI Compliant Credit Card Tokenization

✅ Implement 3DS Challenge Modal. This ensures you display a modal for the end-user to complete a 3DS challenge and is required. Follow the below recipe to learn how to implement a 3DS Challenge Modal:

Complete Checkout with 3DS Challenge

✅ Add Chargeback Protection. This ensures you’ll be 100% protected by chargeback protection.

Learn how to add chargebackProtectionData and x-device-id headers

Once you’ve implemented card tokenization, 3DS, and chargeback protection, call the Card Checkout endpoint. Below is an example of how you’d call the card checkout endpoint:

Request

1 curl --request POST \
2      --url https://api-sandbox.coinflow.cash/api/checkout/card/merchantId \
3      --header 'accept: application/json' \
4      --header 'content-type: application/json' \
5      --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiY3VzdG9tZXIxMjMiLCJtZXJjaGFudElkIjoidHlsZWUiLCJpYXQiOjE3MzQzNjY4NDksImV4cCI6MTczNDQ1MzI0OX0.rxyzFgSZNtIR7KguHyb7MFq2xeDNKH2-3NA49eHH-7Y' \
6      --header 'x-device-id: 12345' \
7      --data '
8 {
9   "subtotal": {
10     "cents": 100
11   },
12   "webhookInfo": {
13     "example": "{\"asdasd\":\"asd\"}"
14   },
15   "authentication3DS": {
16     "colorDepth": 0,
17     "screenHeight": 0,
18     "screenWidth": 0,
19     "timeZone": 0
20   }, // REQUIRED! https://docs.coinflow.cash/recipes/complete-checkout-with-3ds-challenge
21   "card": {
22     "cardToken": "411111YJM5TX1111", 
23     "expYear": "30",
24     "expMonth": "10",
25     "email": "customer@email.com",
26     "firstName": "Dwayne",
27     "lastName": "Johnson",
28     "address1": "385 Prospect Ave",
29     "city": "Brooklyn",
30     "zip": "11215",
31     "state": "NY",
32     "country": "US"
33   },
34   "chargebackProtectionData": [
35     {
36       "productType": "GET_FROM_COINFLOW",
37       "rawProductData": {
38         "example": "{\"description\": \"asd\"}"
39       },
40       "productName": "asdf",
41       "quantity": 1
42     }
43   ], // REQUIRED! https://docs.coinflow.cash/docs/implement-chargeback-protection#how-to-add-chargeback-protection
44   "settlementType": "USDC"
45 }
46 '

Response

{
  "paymentId": "f3fc8a34-680b-4b91-905b-1db5628bbb0e"
}

Enable a Saved Card Checkout
This endpoint will enable a returning user to complete a purchase with a previously saved card. The returning user will need to enter their CVV before confirming the purchase.
🚧 You MUST Complete the following before calling Saved Card Checkout:

✅ Implement Card Tokenization with Coinflow’s Card Form UI. This ensures PCI Compliance on all payments and is required for implementation. Follow the below recipe to learn how to tokenize a credit card. See tab: Refresh Token w/ CVV

PCI Compliant Credit Card Tokenization

✅ Implement 3DS Challenge Modal. This ensures you display a modal for the end-user to complete a 3DS challenge. Follow the below recipe to learn how to implement a 3DS Challenge Modal:

Complete Checkout with 3DS Challenge

✅ Add Chargeback Protection. This ensures you’ll be 100% protected by chargeback protection.
- Learn how to add chargebackProtectionData and x-device-id headers

Once you’ve retrieved the refreshed card token, pass it into the Saved Card Checkout endpoint. Below is an example of how you’d call the saved card checkout endpoint:

Request

1 curl --request POST \
2      --url https://api-sandbox.coinflow.cash/api/checkout/token/merchantId \
3      --header 'accept: application/json' \
4      --header 'content-type: application/json' \
5      --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiY3VzdG9tZXIxMjMiLCJtZXJjaGFudElkIjoidHlsZWUiLCJpYXQiOjE3MzQzNjY4NDksImV4cCI6MTczNDQ1MzI0OX0.rxyzFgSZNtIR7KguHyb7MFq2xeDNKH2-3NA49eHH-7Y' \
6      --header 'x-device-id: 12345' \
7      --data '
8 {
9   "subtotal": {
10     "cents": 100
11   },
12   "webhookInfo": {
13     "example": "{\"asdf\": \"asdf\"}"
14   }, // Pass extra webhook data you want to receive.
15   "authentication3DS": {
16     "colorDepth": 0,
17     "screenHeight": 0,
18     "screenWidth": 0,
19     "timeZone": 0
20   }, // REQUIRED! https://docs.coinflow.cash/recipes/complete-checkout-with-3ds-challenge
21   "token": "411111YJM5TX1111", // REQUIRED! https://docs.coinflow.cash/recipes/pci-compliant-credit-card-tokenization
22   "chargebackProtectionData": [
23     {
24       "productType": "GET_FROM_COINFLOW",
25       "rawProductData": {
26         "example": "{\"description\" : \"asdf\"}"
27       },
28       "productName": "name",
29       "quantity": 1
30     }
31   ], // REQUIRED! https://docs.coinflow.cash/docs/implement-chargeback-protection#how-to-add-chargeback-protection
32   "settlementType": "USDC"
33 }
34 '

Response

{
  "paymentId": "21d842d0-564b-4957-961e-d91ad98aa04b"
}

Optional Implementation: Get payment by id
This endpoint allows your to get details about the payment.

Request

1 curl --request GET \
2      --url https://api-sandbox.coinflow.cash/api/merchant/payments/enhanced/21d842d0-564b-4957-961e-d91ad98aa04b \
3      --header 'Authorization: YOUR_API_KEY' \
4      --header 'accept: application/json'

Response

{
  "info": {
    "firstName": "Dwayne",
    "lastName": "Johnson",
    "email": "customer@email.com",
    "streetAddress": "385 Prospect Ave",
    "city": "Brooklyn",
    "state": "NY",
    "zip": "11215",
    "country": "US",
    "bin": "411111",
    "ip": "35.160.120.126",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
    "expMonth": "10",
    "expYear": "30",
    "ipLocation": {
      "lat": "45.5235",
      "lon": "-122.676",
      "country": "United States",
      "region": "OR",
      "isp": "Amazon.com, Inc.",
      "city": "Portland",
      "zip": "97207"
    },
    "deviceInfo": {
      "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
      "browser": {
        "name": "Chrome",
        "version": "131.0.0.0",
        "major": "131"
      },
      "engine": {
        "name": "Blink",
        "version": "131.0.0.0"
      },
      "os": {
        "name": "Mac OS",
        "version": "10.15.7"
      },
      "device": {
        "vendor": "Apple",
        "model": "Macintosh"
      },
      "cpu": {}
    }
  }
}

Submit a purchase, navigate to your admin dashboard > Purchases to view the latest purchases.