API Implementation
Overview
Merchants can use the following documentation to learn how to implement Rapid with our APIs.
Option 3 - (API)
- Share payer events with Rapid
Sharing major events that a payer makes throughout their lifecycle on your website prior to them making a purchase will allow us to collect more information about them and improve your approval rates.curl --request POST \ --url https://api-sandbox.coinflow.cash/api/events \ --header 'Authorization: YOUR_API_KEY' \ --header 'content-type: application/json' \ --data ' { "eventType": "SignUp", "customerId": "user-123-abc", "country": "US", "username": "therock72", "email": "[email protected]", "firstName": "Dwayne", "lastName": "Johnson" } 'curl --request POST \ --url https://api-sandbox.coinflow.cash/api/events \ --header 'Authorization: YOU_API_KEY' \ --header 'content-type: application/json' \ --data ' { "eventType": "SignIn", "customerId": "user-123-abc", "country": "US", "email": "[email protected]" } 'curl --request POST \ --url https://api-sandbox.coinflow.cash/api/events \ --header 'Authorization: YOUR_API_KEY' \ --header 'content-type: application/json' \ --data ' { "eventType": "SignInFailure", "customerId": "user-123-abc", "country": "US", "email": "[email protected]", "failureReason": "Password Failed" } 'curl --request POST \ --url https://api-sandbox.coinflow.cash/api/events \ --header 'Authorization: YOUR_API_KEY' \ --header 'content-type: application/json' \ --data ' { "eventType": "BuyerChallenge", "type": "thirdPartyKyc", "status": "successfullyFulfilled", "customerId": "user-123-abc", "country": "US", "email": "[email protected]" } ' - Fetch a session key for the customer. This is what you'll pass as the
x-coinflow-auth-session-keyheader.- Note:
x-coinflow-auth-user-idcan be thought of as a unique customer id that you use/define on your systems.
curl --request GET \ --url https://api-sandbox.coinflow.cash/api/auth/session-key \ --header 'x-coinflow-auth-user-id: <customer id>' \ --header 'Authorization: <api key>' \ - Note:
- Get the Totals for the checkout to show the customer a quote with fees
curl --request POST \
--url https://api-sandbox.coinflow.cash/api/checkout/totals/merchantId \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-coinflow-auth-session-key: <SESSION_KEY>' \
--data '
{
"subtotal": {
"cents": 100 // purchase amount
},
"settlementType": "USDC" // This implies funds will settle into your in-product digital wallet
}
'- 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.
Note, Very Important!!: This endpoint requires you to pass a tokenized credit card. Follow this recipe here to learn how to tokenize the credit card.This requires UI component built by Coinflow & Approvely to ensure PCI compliance on all payments.
- Once you retrieve the card token, pass it into the Card Checkout endpoint. Below is an example of how you'd call the card checkout endpoint:
curl --request POST \
--url https://api-sandbox.coinflow.cash/api/checkout/card/merchantId \
--header 'x-coinflow-auth-session-key: <SESSION_KEY>' \
--header 'x-device-id: <DEVICE_ID>' \
--data '
{
"subtotal": {
"cents": 100 // purchase amount
},
"card": {
"expYear": "29",
"expMonth": "10",
"email": "[email protected]",
"firstName": "dwayne",
"lastName": "johnson",
"address1": "123 Rock Road",
"city": "Chicago",
"zip": "60606",
"state": "IL",
"country": "US",
"cardToken": "RETRIEVED_TOKEN_HERE" // Get this from the `CoinflowCardNumberInput` component
},
"chargebackProtectionData": [
{
"productType": "<GET_VALUE_FROM_COINFLOW>", // get this value directly from coinflow.
"productName": "productName",
"quantity": 1,
"rawProductData": { // pass as much data as you have on the purchase. This is free flow json.
"productID": "sword12345",
"productDescription": "A legendary sword with magical powers.",
},
}
],
"settlementType": "USDC",
"webhookInfo": "\"{ productId: 123abc, code: ABC123}\"", // Pass whatever webhook data here
}
'
When passing chargebackProtectionData and x-device-id refer to this link here.
- Optional: After calling the card checkout endpoint, you can optionally call payment by id to get the specific payment details.
- Enable a Saved Card Checkout
- First, fetch the customer and their saved payment methods then, checkout with a previously saved card.
- Note: This endpoint requires you to refresh the saved card's token. Follow this recipe here to learn how to refresh the credit card token with a CVV. Once you retrieve 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:
curl --request POST \
--url https://api-sandbox.coinflow.cash/api/checkout/token/merchantId \
--header 'x-coinflow-auth-session-key: <SESSION_KEY>' \
--header 'x-device-id: ENTER_DEVICE_ID' \
--data '
{
"subtotal": {
"cents": 100
},
"token": "ENTER_TOKEN_HERE", // get this from `CoinflowCvvOnlyInput` Component
"settlementType": "USDC",
"chargebackProtectionData": [
{
"productType": "GET_VALUE_FROM_COINFLOW", // get this value directly from coinflow
"productName": "productName",
"quantity": 1,
"rawProductData": { // pass as much data as you have on the purchase. This is free flow json.
"productID": "sword12345",
"productDescription": "A legendary sword with magical powers.",
},
}
],
"webhookInfo": "\"{ productId: 123abc, code: ABC123}\"", // Pass whatever webhook data here
}
'
When passing chargebackProtectionData and x-device-id refer to this link here.
- Optional: get payment by id details. You may pass the returned paymentId from calling the card checkout endpoint here.
- Enable a purchase with apple pay. Example cURL:
curl --location 'https://api-sandbox.coinflow.cash/api/checkout/apple-pay/merchantId' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'x-coinflow-auth-session-key: <SESSION_KEY>' \ --header 'x-device-id: ENTER_DEVICE_ID' \ --data-raw ' { "subtotal": { "cents": 100 }, "feePercentage": 5, "applePayResponse": { "raw_response": { "details": { "shippingContact": { "emailAddress": "[email protected]" }, "billingContact": { "country": "us", "postalCode": "60699", "locality": "Chicago", "givenName": "dwayne", "familyName": "johnson", "countryCode": "us", "administrativeArea": "IL", "subAdministrativeArea": "cook county", "addressLines": [ "600 S Wacker Dr" ] } } }, "token": "<ENTER_APPLE_PAY_TOKEN>" } } ' - Enable a purchase with google pay. Example cURL:
curl --location 'https://api-sandbox.coinflow.cash/api/checkout/google-pay/merchantId' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'x-coinflow-auth-session-key: <SESSION_KEY>' \ --header 'x-device-id: ENTER_DEVICE_ID' \ --data-raw ' { "subtotal": { "cents": 100 // purchase mount }, "paymentData": { "apiVersionMinor": 0, "apiVersion": 2, "paymentMethodData": { "description": "Visa •••• 1111", "tokenizationData": { "type": "PAYMENT_GATEWAY", "token": "<ENTER_GOOGLE_PAY_TOKEN>" }, "type": "CARD", "info": { "cardNetwork": "VISA", "cardDetails": "1111", "billingAddress": { "address3": "", "sortingCode": "", "address2": "", "countryCode": "US", "address1": "600 S Wacker Dr", "postalCode": "60699", "name": "Dwayne The Rock Johnson", "locality": "Chicago", "administrativeArea": "IL" }, "assuranceDetails": { "cardHolderAuthenticated": false, "accountVerified": true } } }, "email": "[email protected]" } } ' - Submit a purchase, navigate to sandbox.approvely.com > Purchases to view the latest purchases.
Before going live, ensure you've added the chargeback protection script to EVERY PAGE of your site!To learn how to add the script, see this document here .
Updated 4 months ago