How To: Implement Pay-Ins on Marketplaces (API)
How To: Implement Pay-Ins on Marketplaces (API)
This page is for advanced / cryptocurrency-native companies. If that’s not you, head back to the Quickstart for the standard flows.
Coinflow’s marketplace API uses regulated stablecoin rails under the hood. Throughout this page you’ll see fields like wallets.solana, cryptoPayinSettings, settlementToken: "USDC", and paysGasFees in API responses — most marketplaces can ignore them. They’re only relevant if you’re configuring on-chain settlement. The flow you’ll typically implement is: pay-in (card or ACH) → seller balance → seller payout.
Registration
In Coinflow’s marketplace, each seller must have a seller account (to receive payments) and a withdrawer account (to withdraw funds).
Creating a Seller Session Key
Creating a session key is necessary to make client to server calls. The x-coinflow-auth-blockchain and x-coinflow-auth-wallet headers are required because Coinflow uses stablecoin rails under the hood — you can hard-code solana here.
Request
curl --location 'https://api-sandbox.coinflow.cash/api/auth/session-key' \ --header 'Authorization: YOUR_API_KEY' \ --header 'accept: application/json' \ --header 'x-coinflow-auth-blockchain: solana' \ --header 'x-coinflow-auth-wallet: CVrsREanmfBAeZH14PXrBzw4wF8Eh12PJDHYq2feoxUq'
Response
{ "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXQiOiJDVnJzUkVhbm1mQkFlWkgxNFBYckJ6dzR3RjhFaDEyUEpESFlxMmZlb3hVcSIsImJsb2NrY2hhaW4iOiJzb2xhbmEiLCJtZXJjaGFudElkIjoidGFzaGFtYXJrZXQiLCJpYXQiOjE3NTA3MTEyNjcsImV4cCI6MTc1MDc5NzY2N30.Wq1wTl9FXGNADnVdqUaS6sCo0uXLzj2NnfBYAnJr420" }
Seller Registration
-
Create a Seller This endpoint creates a Seller in your registered marketplace.
Requestcurl --location 'https://api-sandbox.coinflow.cash/api/seller' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data-raw ' { "individual": true, "parentId": "tashamarket", "email": "tasha+sellerAA@coinflowlabs.app", "sellerId": "sellerAA", "country": "IT" } ' Response{ "verification": { "hash": "42516ab2-d49b-4659-8347-a2d2ed3ca66b", "reference": "inq_8iTfTTaf1Bba1bdk6C291s8CVQjY", "status": "pending" }, "verificationLink": "https://verify.coinflow.cash/verify?inquiry-id=inq_8iTfTTaf1Bba1bdk6C291s8CVQjY&redirect-uri=https://sandbox-merchant.coinflow.cash/seller/login", "redirectLink": "https://sandbox-merchant.coinflow.cash/seller/login" } Request - US Sellercurl --request POST \ --url https://api-sandbox.coinflow.cash/api/seller \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data ' { "business": true, "info": { "email": "tasha+usseller@coinflowlabs.app", "firstName": "tasha", "surName": "test", "physicalAddress": "201 e randolph st", "city": "chicago", "state": "il", "zip": "60601", "country": "US", "dob": "19900101", "ssn": "1234" }, "individual": true, "parentId": "tashamarket", "email": "tasha+usseller@coinflowlabs.app", "sellerId": "usseller" } ' Response- US SellerOK -
Get Merchant Use this endpoint to reference the seller’s account data. The typical fields a marketplace developer reads are
merchantId,verification,withdrawFees,apiKey, andsettlementAddresses. The full response includes on-chain settlement fields (wallets,cryptoPayinSettings,paysGasFees) — most marketplaces can ignore them.Requestcurl --location 'https://api-sandbox.coinflow.cash/api/merchant/v2' \ --header 'x-coinflow-submerchant-id: sellerAA' \ --header 'Authorization: YOUR_API_KEY' \ --header 'accept: application/json' Advanced: full merchant response (includes on-chain settlement fields)
Response{ "merchant": { "colors": { "style": "rounded" }, "wallets": { "solana": { "feePayer": "242fc2874c4620a28ea14f06365baa51082faf001c16dc5f09d5fee23d526ef3ffa57c1c63c51aa8f284dd164becf35f53ac895aa5e013518a6db66440bea6a72df25c8a5ec07b2fcfab8b4ab06446b446047c02c50765ab544553bfec7c33c1", "usdcPayer": "7b23db13a257d79c3459f02fbe517aee43fcc2311502dd29d2613c8467508644b7cd92be0cf0a5c0a4b31f2e0bf843ca6ecc8111e42460a9d52cd51d1a763f6c86cb716fd06c736e757b0df126640e007b70cee27fc2c263ab07d8beeb2750ff" }, "evm": { "feePayer": "5539472cf865b99f127138970382864dd837bdc8b8422fce553d4fe0968d0a6dba8c1b7c714398eba7a772268e6b516dbdd81256cc36edeac83e411d309878c4cce85206ad2e533700816454c6c31094", "usdcPayer": "c703ca551658c043638bccf251c2ddd491bd23d3fc52a9fd11156e8bccf7a2aa5f1279187ef0060adbfc958b9bc4f8f1f0539529fd1058a91e44637a9aaf43e5109d92e8989d28290e099179ff14fa7b" } }, "settlementAddresses": { "solana": "CVrsREanmfBAeZH14PXrBzw4wF8Eh12PJDHYq2feoxUq", "recipientAddresses": [] }, "cardSettings": { "processor": "mock", "applePayProcessor": "mock", "googlePayProcessor": "mock", "paysFees": false, "paysGasFees": false, "customerEmailNotifications": false, "merchantEmailNotifications": false, "supportsGooglePay": true, "supportsApplePay": true, "saveCardDefault": true, "ignoreProcessorLimit": false, "disable3DSOverride": true, "avsCheck": true, "threeDsChallengePreference": "NoPreference" }, "achSettings": { "processor": "mock", "paysFees": false, "allowDelayedTransactions": false, "customerEmailNotifications": false, "merchantEmailNotifications": false, "instantSettle": false }, "pixSettings": { "paysFees": false, "customerEmailNotifications": false, "merchantEmailNotifications": false }, "ibanSettings": { "paysFees": false, "customerEmailNotifications": false, "merchantEmailNotifications": false }, "cryptoPayinSettings": { "stables": { "feeBps": 50, "paysFees": false, "enabled": true }, "majors": { "feeBps": 100, "paysFees": false, "enabled": true }, "volatile": { "feeBps": 600, "paysFees": false, "enabled": true }, "enabled": false, "maxGasFeePayment": { "cents": 0, "currency": "USD" }, "coinbaseDisabled": false }, "nSureSettings": { "nSureFixedFee": { "cents": 37 }, "nSureInsurance": false, "nSureAchInsurance": false, "enableOverrideReview": false, "overrideReviewHours": 24, "nSureVariableFeeBps": 100 }, "blockConfig": { "failedPaymentAttemptLimit": 3 }, "withdrawFeePayment": { "paysGasFees": { "polygon": false, "eth": false, "base": false, "arbitrum": false, "solana": false }, "paysWithdrawFees": false }, "refundBalanceLimit": { "cents": 500000 }, "_id": "6859b7bb10763eff46a28187", "merchantId": "sellerAA", "verification": { "hash": "42516ab2-d49b-4659-8347-a2d2ed3ca66b", "reference": "inq_8iTfTTaf1Bba1bdk6C291s8CVQjY", "status": "approved" }, "withdrawFees": { "swapBps": 50, "user": { "asap": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 200, "minimum": { "cents": 200, "currency": "USD" } }, "same_day": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 150, "minimum": { "cents": 50, "currency": "USD" } }, "standard": { "fixed": { "cents": 100, "currency": "USD" }, "variableBps": 0, "minimum": { "cents": 0, "currency": "USD" } }, "card": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 200, "minimum": { "cents": 200, "currency": "USD" } }, "iban": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 150, "minimum": { "cents": 200, "currency": "USD" } }, "pix": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 150, "minimum": { "cents": 50, "currency": "USD" } }, "eft": { "fixed": { "cents": 100, "currency": "USD" }, "variableBps": 0, "minimum": { "cents": 0, "currency": "USD" } } }, "business": { "asap": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 200, "minimum": { "cents": 200, "currency": "USD" } }, "same_day": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 100, "minimum": { "cents": 50, "currency": "USD" }, "maximum": { "cents": 5000, "currency": "USD" } }, "standard": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 50, "minimum": { "cents": 50, "currency": "USD" }, "maximum": { "cents": 5000, "currency": "USD" } }, "card": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 0, "minimum": { "cents": 0, "currency": "USD" } }, "iban": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 150, "minimum": { "cents": 200, "currency": "USD" }, "maximum": { "cents": 5000, "currency": "USD" } }, "pix": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 150, "minimum": { "cents": 50, "currency": "USD" }, "maximum": { "cents": 5000, "currency": "USD" } }, "eft": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 50, "minimum": { "cents": 50, "currency": "USD" }, "maximum": { "cents": 5000, "currency": "USD" } } } }, "customWithdrawFees": { "isBundled": false, "lineItemLabel": "Service Charge", "global": { "coverProcessingFees": false, "isFixed": true, "currency": "USD", "cents": 0, "percent": null } }, "apiKey": "afc1364e-0bac-4bf1-abbd-8b5b7de637e2", "apiKeys": [], "kycType": "both", "liquidityNotifications": [], "settlementToken": "USDC", "users": [ { "email": "tasha+sellerAA@coinflowlabs.app", "scope": "seller", "_id": "6859b7bb10763eff46a28188" } ], "ubos": [], "goLiveChecklist": { "programWhitelistRequests": [] }, "hideBranding": false, "onlyShowTotal": false, "skipSendWithdrawEmail": false, "pushToCardEnabled": true, "requireAniCheck": false, "bankPayoutProvider": [ "aptpay" ], "rtpPayoutProvider": "dwolla", "parent": "6849d9a8407a105f5c5dc1fc", "creditSeed": "tashamarket", "withdrawSettlementLocation": "circle", "enforceJwt": true, "enforceCheckoutJwt": false, "externalVerificationLinks": false, "whitelistedAncestorUrls": [], "banDuplicateAccounts": true, "allowAttestedKyc": false, "__v": 1 } } Request- US Sellercurl --location 'https://api-sandbox.coinflow.cash/api/merchant/v2' \ --header 'x-coinflow-submerchant-id: usseller' \ --header 'Authorization: YOUR_API_KEY' \ --header 'accept: application/json' Advanced: full merchant response — US Seller (includes on-chain settlement fields)
Response- US Seller{ "merchant": { "colors": { "style": "rounded" }, "wallets": { "solana": { "feePayer": "b8898b9c0f4615a7917fc915ea3db82625d70769a2e0ec7edd520c12bd7a9266aef9d2efb98d297c7f5ff78a3908272264731891c16414a53d05142ae72cb099c5cbf16dd04f1c2b3a8503f751cb672b4228c10edc8b2420017915f6e4bce4eb", "usdcPayer": "26c3f323b26c104f826dc2df33dc27aadbe939cf06de178cd503a03804ea58d8f697ed630ea757d49c64cf9ed30574f4297bc88a9ebd7abe788e6a3eaeb3f838930f449d856558c30cbb56bd81bbe0ee5e10028783e1a27e0fbae1cc7215c7c4" }, "evm": { "feePayer": "6101094cfbb183d342bbec088c646625eb48e66081062a825c951cdb3a04d636d267f7f1b2cbe10d844157e96727c1f91f4a21ce1aee89e01628c7e3fd390fbf178b4a4ef7daaea36812b31c977cc95e", "usdcPayer": "827205dab06cc539897888add0f6e66ad565f1ae15162e4fcce821f9bb18ac92dccea00ec9d2d6d18fcdf81a3fc581ae9c7a2b3cf09cc53a4c5a2080d9dd6425ca725fb588e672ca0530d2b5961f64a5" } }, "settlementAddresses": { "solana": "BWeSjNQyEgyU2hxtmfAagk3jRk4S3mtFJhmUPYAGfoJ6", "recipientAddresses": [] }, "cardSettings": { "processor": "mock", "applePayProcessor": "mock", "googlePayProcessor": "mock", "paysFees": false, "paysGasFees": false, "customerEmailNotifications": false, "merchantEmailNotifications": false, "supportsGooglePay": true, "supportsApplePay": true, "saveCardDefault": true, "ignoreProcessorLimit": false, "disable3DSOverride": true, "avsCheck": true, "threeDsChallengePreference": "NoPreference" }, "achSettings": { "processor": "mock", "paysFees": false, "allowDelayedTransactions": false, "customerEmailNotifications": false, "merchantEmailNotifications": false, "instantSettle": false }, "pixSettings": { "paysFees": false, "customerEmailNotifications": false, "merchantEmailNotifications": false }, "ibanSettings": { "paysFees": false, "customerEmailNotifications": false, "merchantEmailNotifications": false }, "cryptoPayinSettings": { "stables": { "feeBps": 50, "paysFees": false, "enabled": true }, "majors": { "feeBps": 100, "paysFees": false, "enabled": true }, "volatile": { "feeBps": 600, "paysFees": false, "enabled": true }, "enabled": false, "maxGasFeePayment": { "cents": 0, "currency": "USD" }, "coinbaseDisabled": false }, "nSureSettings": { "nSureFixedFee": { "cents": 37 }, "nSureInsurance": false, "nSureAchInsurance": false, "enableOverrideReview": false, "overrideReviewHours": 24, "nSureVariableFeeBps": 100 }, "blockConfig": { "failedPaymentAttemptLimit": 3 }, "withdrawFeePayment": { "paysGasFees": { "polygon": false, "eth": false, "base": false, "arbitrum": false, "solana": false }, "paysWithdrawFees": false }, "refundBalanceLimit": { "cents": 500000 }, "_id": "6859b20210763eff46a27da6", "merchantId": "usseller", "verification": { "hash": "cda3090cf0c6f580c0e7c414adefa61fa9f22c7b", "reference": "ver_RDuHxp464KWF1e1LMPCsp7ay7ygB", "status": "approved" }, "withdrawFees": { "swapBps": 50, "user": { "asap": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 200, "minimum": { "cents": 200, "currency": "USD" } }, "same_day": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 150, "minimum": { "cents": 50, "currency": "USD" } }, "standard": { "fixed": { "cents": 100, "currency": "USD" }, "variableBps": 0, "minimum": { "cents": 0, "currency": "USD" } }, "card": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 200, "minimum": { "cents": 200, "currency": "USD" } }, "iban": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 150, "minimum": { "cents": 200, "currency": "USD" } }, "pix": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 150, "minimum": { "cents": 50, "currency": "USD" } }, "eft": { "fixed": { "cents": 100, "currency": "USD" }, "variableBps": 0, "minimum": { "cents": 0, "currency": "USD" } } }, "business": { "asap": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 200, "minimum": { "cents": 200, "currency": "USD" } }, "same_day": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 100, "minimum": { "cents": 50, "currency": "USD" }, "maximum": { "cents": 5000, "currency": "USD" } }, "standard": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 50, "minimum": { "cents": 50, "currency": "USD" }, "maximum": { "cents": 5000, "currency": "USD" } }, "card": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 0, "minimum": { "cents": 0, "currency": "USD" } }, "iban": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 150, "minimum": { "cents": 200, "currency": "USD" }, "maximum": { "cents": 5000, "currency": "USD" } }, "pix": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 150, "minimum": { "cents": 50, "currency": "USD" }, "maximum": { "cents": 5000, "currency": "USD" } }, "eft": { "fixed": { "cents": 0, "currency": "USD" }, "variableBps": 50, "minimum": { "cents": 50, "currency": "USD" }, "maximum": { "cents": 5000, "currency": "USD" } } } }, "customWithdrawFees": { "isBundled": false, "lineItemLabel": "Service Charge", "global": { "coverProcessingFees": false, "isFixed": true, "currency": "USD", "cents": 0, "percent": null } }, "apiKey": "2f104ced-6938-4a5b-bb42-66bcdc0e6b08", "apiKeys": [], "kycType": "both", "liquidityNotifications": [], "settlementToken": "USDC", "users": [ { "email": "tasha+usseller@coinflowlabs.app", "scope": "seller", "_id": "6859b20210763eff46a27da7" } ], "ubos": [], "goLiveChecklist": { "programWhitelistRequests": [] }, "hideBranding": false, "onlyShowTotal": false, "skipSendWithdrawEmail": false, "pushToCardEnabled": true, "requireAniCheck": false, "bankPayoutProvider": [ "aptpay" ], "rtpPayoutProvider": "dwolla", "parent": "6849d9a8407a105f5c5dc1fc", "creditSeed": "tashamarket", "withdrawSettlementLocation": "circle", "enforceJwt": true, "enforceCheckoutJwt": false, "externalVerificationLinks": false, "whitelistedAncestorUrls": [], "banDuplicateAccounts": true, "allowAttestedKyc": false, "__v": 0 } } -
Creating a Seller Session Key Creating a session key is required for client-to-server calls. The
x-coinflow-auth-blockchainandx-coinflow-auth-walletheaders are required because Coinflow uses stablecoin rails under the hood — you can hard-codesolanaand pass the seller’ssettlementAddresses.solanavalue.Requestcurl --location 'https://api-sandbox.coinflow.cash/api/auth/session-key' \ --header 'Authorization: YOUR_API_KEY' \ --header 'accept: application/json' \ --header 'x-coinflow-auth-blockchain: solana' \ --header 'x-coinflow-auth-wallet: CVrsREanmfBAeZH14PXrBzw4wF8Eh12PJDHYq2feoxUq' Response{ "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXQiOiJDVnJzUkVhbm1mQkFlWkgxNFBYckJ6dzR3RjhFaDEyUEpESFlxMmZlb3hVcSIsImJsb2NrY2hhaW4iOiJzb2xhbmEiLCJtZXJjaGFudElkIjoidGFzaGFtYXJrZXQiLCJpYXQiOjE3NTA3MTEyNjcsImV4cCI6MTc1MDc5NzY2N30.Wq1wTl9FXGNADnVdqUaS6sCo0uXLzj2NnfBYAnJr420" } -
Get Withdrawer Use this endpoint to reference the seller’s withdrawer data.
curl --request GET \ --url https://api-sandbox.coinflow.cash/api/withdraw \ --header 'accept: application/json' \ --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXQiOiJDVnJzUkVhbm1mQkFlWkgxNFBYckJ6dzR3RjhFaDEyUEpESFlxMmZlb3hVcSIsImJsb2NrY2hhaW4iOiJzb2xhbmEiLCJtZXJjaGFudElkIjoidGFzaGFtYXJrZXQiLCJpYXQiOjE3NTA3MTEyNjcsImV4cCI6MTc1MDc5NzY2N30.Wq1wTl9FXGNADnVdqUaS6sCo0uXLzj2NnfBYAnJr420' { "withdrawer": { "_id": "6859b7bbe36b426f2df63d50", "__v": 0, "availability": { "status": "Functional", "reason": "Initial", "editor": "system", "updatedAt": "2025-06-23T20:23:23.516Z" }, "currency": "EUR", "email": "tasha+sellerAA@coinflowlabs.app", "merchant": "6849d9a8407a105f5c5dc1fc", "originalCurrency": "EUR", "riskScoreOverride": false, "user": true, "verification": { "hash": "42516ab2-d49b-4659-8347-a2d2ed3ca66b", "reference": "inq_8iTfTTaf1Bba1bdk6C291s8CVQjY", "status": "approved" }, "wallets": [ { "wallet": "CVrsREanmfBAeZH14PXrBzw4wF8Eh12PJDHYq2feoxUq", "blockchain": "solana" } ], "watchlistExempt": "Unknown", "bankAccounts": [], "cards": [], "ibans": [], "pixes": [], "efts": [], "rtpDisabled": false, "cardDisabled": false } }
Payment
Card Payments
-
Fetch a session key This creates a JWT token for the payer, and authorizes the payer to call these endpoints client-to-server. You will pass the returned session key as
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.
Request1 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' Response{ "key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiY3VzdG9tZXIxMjMiLCJtZXJjaGFudElkIjoidGFzaGFtYXJrZXQiLCJpYXQiOjE3NTA3MTE3NTksImV4cCI6MTc1MDc5ODE1OX0.2bY7ZoEPIEzewY3Y4X-NpaVA-L9bZ67-3INOMcCYLVQ" } - Note:
-
Get the Totals for the checkout to show the customer a quote inclusive of all fees.
Request1 curl --request POST \ 2 --url https://api-sandbox.coinflow.cash/api/checkout/totals/sellerAA \ 3 --header 'accept: application/json' \ 4 --header 'content-type: application/json' \ 5 --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiY3VzdG9tZXIxMjMiLCJtZXJjaGFudElkIjoidGFzaGFtYXJrZXQiLCJpYXQiOjE3NTA3MTE3NTksImV4cCI6MTc1MDc5ODE1OX0.2bY7ZoEPIEzewY3Y4X-NpaVA-L9bZ67-3INOMcCYLVQ' \ 6 --data ' 7 { 8 "subtotal": { 9 "cents": 100 10 }, 11 "settlementType": "USDC" 12 } 13 ' Response{ "card": { "subtotal": { "cents": 100, "currency": "USD" }, "creditCardFees": { "cents": 40, "currency": "USD" }, "chargebackProtectionFees": { "cents": 0, "currency": "USD" }, "gasFees": { "cents": 0, "currency": "USD" }, "total": { "cents": 140, "currency": "USD" }, "settlement": { "subtotal": { "cents": 100, "currency": "USD" }, "creditCardFees": { "cents": 40, "currency": "USD" }, "chargebackProtectionFees": { "cents": 0, "currency": "USD" }, "gasFees": { "cents": 0, "currency": "USD" }, "total": { "cents": 140, "currency": "USD" } }, "exchangeRate": 1, "basis": { "cents": 100, "currency": "USD" } }, "ach": { "subtotal": { "cents": 100, "currency": "USD" }, "creditCardFees": { "cents": 100, "currency": "USD" }, "chargebackProtectionFees": { "cents": 0, "currency": "USD" }, "gasFees": { "cents": 0, "currency": "USD" }, "total": { "cents": 200, "currency": "USD" }, "settlement": { "subtotal": { "cents": 100, "currency": "USD" }, "creditCardFees": { "cents": 100, "currency": "USD" }, "chargebackProtectionFees": { "cents": 0, "currency": "USD" }, "gasFees": { "cents": 0, "currency": "USD" }, "total": { "cents": 200, "currency": "USD" } }, "exchangeRate": 1, "basis": { "cents": 100, "currency": "USD" } }, "googlePay": { "subtotal": { "cents": 100, "currency": "USD" }, "creditCardFees": { "cents": 40, "currency": "USD" }, "chargebackProtectionFees": { "cents": 0, "currency": "USD" }, "gasFees": { "cents": 0, "currency": "USD" }, "total": { "cents": 140, "currency": "USD" }, "settlement": { "subtotal": { "cents": 100, "currency": "USD" }, "creditCardFees": { "cents": 40, "currency": "USD" }, "chargebackProtectionFees": { "cents": 0, "currency": "USD" }, "gasFees": { "cents": 0, "currency": "USD" }, "total": { "cents": 140, "currency": "USD" } }, "exchangeRate": 1, "basis": { "cents": 100, "currency": "USD" } }, "applePay": { "subtotal": { "cents": 100, "currency": "USD" }, "creditCardFees": { "cents": 40, "currency": "USD" }, "chargebackProtectionFees": { "cents": 0, "currency": "USD" }, "gasFees": { "cents": 0, "currency": "USD" }, "total": { "cents": 140, "currency": "USD" }, "settlement": { "subtotal": { "cents": 100, "currency": "USD" }, "creditCardFees": { "cents": 40, "currency": "USD" }, "chargebackProtectionFees": { "cents": 0, "currency": "USD" }, "gasFees": { "cents": 0, "currency": "USD" }, "total": { "cents": 140, "currency": "USD" } }, "exchangeRate": 1, "basis": { "cents": 100, "currency": "USD" } }, "credits": { "subtotal": { "cents": 100, "currency": "USD" }, "creditCardFees": { "cents": 0, "currency": "USD" }, "chargebackProtectionFees": { "cents": 0, "currency": "USD" }, "gasFees": { "cents": 0, "currency": "USD" }, "total": { "cents": 100, "currency": "USD" }, "settlement": { "subtotal": { "cents": 100, "currency": "USD" }, "creditCardFees": { "cents": 0, "currency": "USD" }, "chargebackProtectionFees": { "cents": 0, "currency": "USD" }, "gasFees": { "cents": 0, "currency": "USD" }, "total": { "cents": 100, "currency": "USD" } }, "exchangeRate": 1, "basis": { "cents": 100, "currency": "USD" } } } Advanced: USDC totals block (only relevant for on-chain settlement)
If your account is configured for stablecoin pay-ins, the totals response also includes a
usdcblock alongside the payment methods above:Response (usdc block)"usdc": { "subtotal": { "cents": 100, "currency": "USD" }, "creditCardFees": { "cents": 0, "currency": "USD" }, "chargebackProtectionFees": { "cents": 0, "currency": "USD" }, "gasFees": { "cents": 0, "currency": "USD" }, "total": { "cents": 100, "currency": "USD" }, "settlement": { "subtotal": { "cents": 100, "currency": "USD" }, "creditCardFees": { "cents": 0, "currency": "USD" }, "chargebackProtectionFees": { "cents": 0, "currency": "USD" }, "gasFees": { "cents": 0, "currency": "USD" }, "total": { "cents": 100, "currency": "USD" } }, "exchangeRate": 1, "basis": { "cents": 100, "currency": "USD" } } -
Tokenize the Credit Card Number. See tab:
Tokenize New Card -
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. Below is an example of how you’d call the card checkout endpoint:
-
Request
1 curl --location 'https://api-sandbox.coinflow.cash/api/checkout/card/sellerAA' \ 2 --header 'accept: application/json' \ 3 --header 'content-type: application/json' \ 4 --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiY3VzdG9tZXIxMjMiLCJtZXJjaGFudElkIjoidGFzaGFtYXJrZXQiLCJpYXQiOjE3NTA3MTE3NTksImV4cCI6MTc1MDc5ODE1OX0.2bY7ZoEPIEzewY3Y4X-NpaVA-L9bZ67-3INOMcCYLVQ' \ 5 --data-raw ' 6 { 7 "subtotal": { 8 "currency": "USD", 9 "cents": 500 10 }, 11 "webhookInfo": { 12 "example": "{\"platformId\": \"123abc\"}" 13 }, 14 "card": { 15 "cardToken": "411111YJM5TX1111", 16 "expYear": "30", 17 "expMonth": "10", 18 "email": "test@gmail.com", 19 "firstName": "sdfadfsd", 20 "lastName": "sdfsdfsd", 21 "address1": "380 prospect ave", 22 "city": "brooklyn", 23 "zip": "11215", 24 "state": "ny", 25 "country": "US" 26 }, 27 "feePercentage": 2, // Percentage fee marketplace takes from each transaction 28 "settlementType": "USDC" 29 } 30 ' Response{ "paymentId": "f3fc8a34-680b-4b91-905b-1db5628bbb0e" }
- Re-tokenize a saved card number. See tab:
Refresh Token w/ CVV - 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. Once you’ve retrieved the refreshed card token, pass it into the Saved Card Checkout endpoint. Below is an example request:
Request
1 curl --request POST \ 2 --url https://api-sandbox.coinflow.cash/api/checkout/token/testtest \ 3 --header 'accept: application/json' \ 4 --header 'content-type: application/json' \ 5 --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiY3VzdG9tZXIxMjMiLCJtZXJjaGFudElkIjoidGFzaGFtYXJrZXQiLCJpYXQiOjE3NTA3MTE3NTksImV4cCI6MTc1MDc5ODE1OX0.2bY7ZoEPIEzewY3Y4X-NpaVA-L9bZ67-3INOMcCYLVQ' \ 6 --data ' 7 { 8 "subtotal": { 9 "currency": "USD", 10 "cents": 500 11 }, 12 "webhookInfo": { 13 "example": "{\"wineId\": \"123abc\"}" 14 }, 15 "settlementType": "USDC", 16 "token": "411111YJM5TX1111", 17 "feePercentage": 2 // Percentage fee marketplace takes from each transaction 18 } 19 '
Response
{ "paymentId": "0090c04b-1ae8-4672-a108-32874df36f11" }
- 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": {} } } }
- At this point, you’ve successfully made a purchase with a new card and with a saved card. Next, lets add 3DS for card purchases. Please reach out to the Coinflow team when you’ve reached this step so we can configure 3DS on your account.
Adding 3DS to Card Checkout
Adding Chargeback Protection
- Add the chargeback protection script to every page of your app.
This script allows our provider to analyze user behavior and determine if the behavior could lead to fraud.
- Use the sandbox partnerId provided by Coinflow.
- Pass the
chargebackProtectionDataobject to the new and saved card checkout as well as the below headers. See an example of what the request will look like when you pass chargeback protection data to the new card checkout endpoint.x-device-id- Get this after adding the script in step 1x-coinflow-client-ip- the payer’s ip addressuser-agent- the payer’s User Agent
Request1 curl --location 'https://api-sandbox.coinflow.cash/api/checkout/card/sellerAA' \ 2 --header 'accept: application/json' \ 3 --header 'content-type: application/json' \ 4 --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoiY3VzdG9tZXIxMjMiLCJtZXJjaGFudElkIjoidGFzaGFtYXJrZXQiLCJpYXQiOjE3NTA3MTE3NTksImV4cCI6MTc1MDc5ODE1OX0.2bY7ZoEPIEzewY3Y4X-NpaVA-L9bZ67-3INOMcCYLVQ' \ 5 --header 'user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.3 Safari/605.1.15' \ 6 --header 'x-coinflow-client-ip: 123.123.123.123' \ 7 --header 'x-device-id: 123456789' \ 8 --data-raw ' 9 { 10 "subtotal": { 11 "currency": "USD", 12 "cents": 500 13 }, 14 "webhookInfo": { 15 "example": "{\"platformId\": \"123abc\"}" 16 }, 17 "card": { 18 "cardToken": "411111YJM5TX1111", 19 "expYear": "30", 20 "expMonth": "10", 21 "email": "test@gmail.com", 22 "firstName": "sdfadfsd", 23 "lastName": "sdfsdfsd", 24 "address1": "380 prospect ave", 25 "city": "brooklyn", 26 "zip": "11215", 27 "state": "ny", 28 "country": "US" 29 }, 30 "feePercentage": 2, // Percentage fee marketplace takes from each transaction 31 "settlementType": "USDC", 32 "chargebackProtectionData": [ 33 { 34 "productType": "alcohol", // This may change 35 "rawProductData": { 36 "example": "{\"description\": \"pass as much description about the purchase here\", \"region\": \"CA\", \"yearsOld\": 20}" 37 }, 38 "productName": "California Cab", 39 "quantity": 1 40 } 41 ], 42 } 43 '
Displaying Seller Earnings from Purchases
- Get Balances
This endpoint allows you to see how much the seller has available to withdraw at any time.
Request
curl --request GET \ --url https://api-sandbox.coinflow.cash/api/customer/balances/sellerAA \ --header 'accept: application/json' \ --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXQiOiJDVnJzUkVhbm1mQkFlWkgxNFBYckJ6dzR3RjhFaDEyUEpESFlxMmZlb3hVcSIsImJsb2NrY2hhaW4iOiJzb2xhbmEiLCJtZXJjaGFudElkIjoidGFzaGFtYXJrZXQiLCJpYXQiOjE3NTA3MTEyNjcsImV4cCI6MTc1MDc5NzY2N30.Wq1wTl9FXGNADnVdqUaS6sCo0uXLzj2NnfBYAnJr420' Response{ "credits": { "cents": 0 }, "usdc": { "cents": 490 } }