How To: Implement Wire Payins

API Integration

Completing a First Time Wire Payment

1. Initiate a US Wire Domestic Payments Checkout (for New Accounts only) In a real life scenario, the payer is expected to navigate to their banking app and send the wire payment to Coinflow using the details provided in the below response body. Once Coinflow receives the funds, we will settle the funds to your merchant settlement location.

   The account_number field must be the customer’s raw bank account number. Tokenized bank account numbers from third-party providers are not accepted.

   curl --request POST \
        --url https://api-sandbox.coinflow.cash/api/checkout/wire \
        --header 'accept: application/json' \
        --header 'content-type: application/json' \
        --header 'x-coinflow-auth-session-key: YOUR_SESSION_KEY' \
        --data '
   {
     "subtotal": {
       "currency": "USD",
       "cents": 500
     },
     "data": {
       "account_number": "1111222233331111",
       "alias": "Wire Acct 1",
       "email": "myemail@gmail.com",
       "firstName": "Mike",
       "lastName": "Myers",
       "address1": "201 E Randolph St",
       "city": "Chicago",
       "state": "IL",
       "zip": "60601",
       "country": "US",
       "wireRoutingNumber": "021052367"
     },
     "merchantId": "mymerchantid" //Replace with your merchant ID
   }
   '

   {
     "account_number": "86063057",
     "wireRoutingNumber": "071925444",
     "address": {
       "address1": "1 E Erie St",
       "city": "Chicago",
       "state": "IL",
       "zip": "60611",
       "country": "US"
     },
     "due": "2025-11-03T15:07:11.068Z",
     "paymentId": "/guides/checkout/payment-methods/payment-methods/wires/implement-wire-payments",
     "recipientName": "Coinflow Labs",
     "expires": "2025-11-03T15:07:11.068Z",
     "amount": {
       "cents": 700,
       "currency": "USD"
     }
   }

2. Force Settle the payment (only Sandbox) In a real life scenario, the payer is expected to navigate to their banking app and send the wire payment to Coinflow per the instructions in step 2. In sandbox, we dont provide a sandbox env so you can simulate sending a wire by force settling the payment.

   curl --request PUT \
        --url https://api-sandbox.coinflow.cash/api/merchant/payments//guides/checkout/payment-methods/payment-methods/wires/implement-wire-payments/settle \
        --header 'Authorization: YOUR_API_KEY' \
        --header 'accept: application/json'

3. Get Payment by id

   {
     "_id": "6904d09f311ec2b9569f678a",
     "paymentId": "/guides/checkout/payment-methods/payment-methods/wires/implement-wire-payments",
     "totals": {
       "subtotal": {
         "cents": 500,
         "currency": "USD"
       },
       "creditCardFees": {
         "cents": 200,
         "currency": "USD"
       },
       "chargebackProtectionFees": {
         "cents": 0,
         "currency": "USD"
       },
       "gasFees": {
         "cents": 0,
         "currency": "USD"
       },
       "fxFees": {
         "cents": 0,
         "currency": "USD"
       },
       "total": {
         "cents": 700,
         "currency": "USD"
       },
       "merchantPaidGasFees": {
         "cents": 0,
         "currency": "USD"
       }
     },
     "customer": "65e74467d7fd30773bdc531d",
     "merchant": "6840bca9c7cb21ee5baaae76",
     "chargebackProtectionDecision": "Not Enabled",
     "wireInfo": {
       "status": "SETTLED",
       "processor": "mock",
       "expiration": "2025-11-03T15:07:11.068Z",
       "token": "ca0c6762-22c1-4880-8be7-b3c35e00fe42"
     },
     "exchangeInfo": {
       "amount": {
         "subtotal": {
           "cents": 500,
           "currency": "USD"
         },
         "creditCardFees": {
           "cents": 200,
           "currency": "USD"
         },
         "chargebackProtectionFees": {
           "cents": 0,
           "currency": "USD"
         },
         "gasFees": {
           "cents": 0,
           "currency": "USD"
         },
         "fxFees": {
           "cents": 0,
           "currency": "USD"
         },
         "total": {
           "cents": 700,
           "currency": "USD"
         },
         "merchantPaidGasFees": {
           "cents": 0,
           "currency": "USD"
         }
       },
       "rate": 1,
       "base": {
         "cents": 500,
         "currency": "USD"
       }
     },
     "createdAt": "2025-10-31T15:07:11.077Z",
     "updatedAt": "2025-10-31T15:11:00.888Z",
     "__v": 0,
     "signature": "xMTqnfZCm9qgYwkSquPBXvATWx5uGxaiQsBMT6mTTjBnqMMk16RrqCphN6nXPKjmoMFBaeTWNHVJoKbs4DYRv3m"
   }

Completing a Wire Payment for a Returning Customer

1. Get Customer

   curl --request GET \
        --url https://api-sandbox.coinflow.cash/api/customer/v2 \
        --header 'accept: application/json' \
        --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXQiOiI5cnB2Mlc2cXlTaHdjd1RnWlhwaUZ1QzVrRkdZcHpoWXVnbXBLSzVMczRLdCIsImJsb2NrY2hhaW4iOiJzb2xhbmEiLCJtZXJjaGFudElkIjoibWVsbG8iLCJpYXQiOjE3NjE5MjM5NDksImV4cCI6MTc2MjAxMDM0OX0.dv6x4GHXfc46X6yYF7CN6WLyUvv7UPEflqXQDwATHpE'

   {
       "customer": {
           "_id": "65e74467d7fd30773bdc531d",
           "email": "myemail@gmail.com",
           "chargebackProtectionEnabled": false,
           "createdAt": "2024-03-05T16:12:23.356Z",
           "__v": 0,
           "merchant": "63c73b64fe798b3fdb56e3aa",
           "failedAttemptSetting": "Standard",
           "verificationSetting": "Enforced",
           "exempt3DS": false,
           "customerId": "9rpv2W6qyShwcwTgZXpiFuC5kFGYpzhYugmpKK5Ls4Kt",
           "availability": {
               "status": "Functional",
               "reason": "test",
               "editor": "tasha",
               "updatedAt": "2025-10-22T16:43:04.307Z"
           },
           "bankAccounts": [
               {
                   "alias": "Wire Acct 1",
                   "token": "ca0c6762-22c1-4880-8be7-b3c35e00fe42",
                   "wireRoutingNumber": "021052367",
                   "last4": "1111",
                   "accountHash": "2d9d0a5dd76cfa7c8b1aef66ff5e53ad6f6b8650",
                   "accountNumberOnlyHash": "cd8609cc4c2e0df35388452600bd16e08acda490",
                   "reference": "666886ad30fd8f1205e77841"
               }
           ]
       }
   }

2. Initiate a US Wire Domestic Payments Checkout (Saved Account) In a real life scenario, the payer is expected to navigate to their banking app and send the wire payment to Coinflow using the details provided in the below response body. Once Coinflow receives the funds, we will settle the funds to your merchant settlement location.

   If the saved account is missing the raw account number or wire routing number, the API will return a 412 response indicating which fields are needed. You must prompt the customer for the missing details and re-submit with the accountNumber and/or wireRoutingNumber fields included.

   412 Response Example:

   {
     "accountNumberRequired": true,
     "wireRoutingNumberRequired": false,
     "type": "bank-details-required"
   }

   Re-submit with missing details:

   curl --request POST \
        --url https://api-sandbox.coinflow.cash/api/checkout/wire/token \
        --header 'accept: application/json' \
        --header 'content-type: application/json' \
        --header 'x-coinflow-auth-session-key: YOUR_SESSION_KEY' \
        --data '
   {
     "subtotal": {
       "currency": "USD",
       "cents": 400
     },
     "merchantId": "mello",
     "token": "ca0c6762-22c1-4880-8be7-b3c35e00fe42",
     "accountNumber": "1111222233331111",
     "wireRoutingNumber": "021052367"
   }
   '

   Standard request (when account details are already on file):

   curl --request POST \
        --url https://api-sandbox.coinflow.cash/api/checkout/wire/token \
        --header 'accept: application/json' \
        --header 'content-type: application/json' \
        --header 'x-coinflow-auth-session-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXQiOiI5cnB2Mlc2cXlTaHdjd1RnWlhwaUZ1QzVrRkdZcHpoWXVnbXBLSzVMczRLdCIsImJsb2NrY2hhaW4iOiJzb2xhbmEiLCJtZXJjaGFudElkIjoibWVsbG8iLCJpYXQiOjE3NjE5MjM5NDksImV4cCI6MTc2MjAxMDM0OX0.dv6x4GHXfc46X6yYF7CN6WLyUvv7UPEflqXQDwATHpE' \
        --data '
   {
     "subtotal": {
       "currency": "USD",
       "cents": 400
     },
     "merchantId": "mello",
     "token": "ca0c6762-22c1-4880-8be7-b3c35e00fe42",
     "wireRoutingNumber": "021052367"
   }
   '

   {
     "account_number": "86063057",
     "wireRoutingNumber": "071925444",
     "address": {
       "address1": "1 E Erie St",
       "city": "Chicago",
       "state": "IL",
       "zip": "60611",
       "country": "US"
     },
     "due": "2025-11-03T15:21:08.081Z",
     "paymentId": "6cd87e63-000c-48ef-8673-5f05bcc5d651",
     "recipientName": "Coinflow Labs",
     "expires": "2025-11-03T15:21:08.081Z",
     "amount": {
       "cents": 600,
       "currency": "USD"
     }
   }

3. Force Settle the payment (only Sandbox) In a real life scenario, the payer is expected to navigate to their banking app and send the wire payment to Coinflow per the instructions in step 2. In sandbox, we dont provide a sandbox env so you can simulate sending a wire by force settling the payment.

   curl --request PUT \
        --url https://api-sandbox.coinflow.cash/api/merchant/payments/6cd87e63-000c-48ef-8673-5f05bcc5d651/settle \
        --header 'Authorization: YOUR_API_KEY' \
        --header 'accept: application/json'

4. Get Payment by id

   curl --request GET \
        --url https://api-sandbox.coinflow.cash/api/merchant/payments/6cd87e63-000c-48ef-8673-5f05bcc5d651 \
        --header 'Authorization: YOUR_API_KEY' \
        --header 'accept: application/json'

   {
     "_id": "6904d3e4311ec2b9569f6c83",
     "paymentId": "6cd87e63-000c-48ef-8673-5f05bcc5d651",
     "totals": {
       "subtotal": {
         "cents": 400,
         "currency": "USD"
       },
       "creditCardFees": {
         "cents": 200,
         "currency": "USD"
       },
       "chargebackProtectionFees": {
         "cents": 0,
         "currency": "USD"
       },
       "gasFees": {
         "cents": 0,
         "currency": "USD"
       },
       "fxFees": {
         "cents": 0,
         "currency": "USD"
       },
       "total": {
         "cents": 600,
         "currency": "USD"
       },
       "merchantPaidGasFees": {
         "cents": 0,
         "currency": "USD"
       }
     },
     "customer": "65e74467d7fd30773bdc531d",
     "merchant": "6840bca9c7cb21ee5baaae76",
     "chargebackProtectionDecision": "Not Enabled",
     "wireInfo": {
       "status": "SETTLED",
       "processor": "mock",
       "expiration": "2025-11-03T15:21:08.081Z",
       "token": "ca0c6762-22c1-4880-8be7-b3c35e00fe42"
     },
     "exchangeInfo": {
       "amount": {
         "subtotal": {
           "cents": 400,
           "currency": "USD"
         },
         "creditCardFees": {
           "cents": 200,
           "currency": "USD"
         },
         "chargebackProtectionFees": {
           "cents": 0,
           "currency": "USD"
         },
         "gasFees": {
           "cents": 0,
           "currency": "USD"
         },
         "fxFees": {
           "cents": 0,
           "currency": "USD"
         },
         "total": {
           "cents": 600,
           "currency": "USD"
         },
         "merchantPaidGasFees": {
           "cents": 0,
           "currency": "USD"
         }
       },
       "rate": 1,
       "base": {
         "cents": 400,
         "currency": "USD"
       }
     },
     "createdAt": "2025-10-31T15:21:08.088Z",
     "updatedAt": "2025-10-31T15:22:35.357Z",
     "__v": 0,
     "signature": "2YDSVFKfCq4ZeCUiG935kKPwBUVNxgymxZ3UED94HhJ2emH55TMa24VfQwmB9oHSzJmUWMb5hX62gGB1BvigayfD"
   }

📘 Disclaimers about Wire Payments

• Payment expires in 3 days.
• Payers should be warned to not send the payment after the expiration time or they will be charged a return fee. This return fee cannot be reversed by Coinflow. The cost of return fees are outlined in your MSA.

UI Implementation

React / React Native Example

1. Create the user’s session key
2. Create JWT Token

   curl --request POST \
        --url https://api-sandbox.coinflow.cash/api/checkout/jwt-token \
        --header 'Authorization: YOUR_API_KEY' \
        --header 'accept: application/json' \
        --header 'content-type: application/json' \
        --data '
   {
     "subtotal": {
       "currency": "USD",
       "cents": 200
     }
   }
   '
3. Implement CoinflowPurchase component

   function App() {
     return (
       <div className="App" style={{height: "900px"}}>
         <CoinflowPurchase
           sessionKey={"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXQiOiI5cnB2Mlc2cXlTaHdjd1RnWlhwaUZ1QzVrRkdZcHpoWXVnbXBLSzVMczRLdCIsImJsb2NrY2hhaW4iOiJzb2xhbmEiLCJtZXJjaGFudElkIjoibWVsbG8iLCJpYXQiOjE3NjE5MjM5NDksImV4cCI6MTc2MjAxMDM0OX0.dv6x4GHXfc46X6yYF7CN6WLyUvv7UPEflqXQDwATHpE"}
           merchantId={"mello"}
           env={"sandbox"}
           jwtToken={"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoi456C4oKW26LXguCpoOaYguuAhOyEiOOGgeC0kOSYgemvoeiYgOOFoOu4gueJkOCsnOmaouaUmOKAh-KsoM2PduGghO6Ak-yAg-iAl-OgqMKJ5pSV6JiI4aq4xrHiqYPklIris7nloZLktZ_iiLLCjOahpeaKl-GnluWhie6pgOSUkumpieWKsOC7gOCmhOiot-mVluWEoeOEp-yEoOSGp-yBg-iXg-iVpOKEieSOgu2Sp-qOg-eMpeaDsuWBheyHiuSEouWXg-WDgO-FoeWXheOGoeqDtuqts-iJguqNt-uLgO2Nt-SSouydoeKUsOmdlOqplOKLguWDs-eLguOYjeaZseq3gO-AoeqJk-eEgNeyXHUwMDAwIiwibWVyY2hhbnRJZCI6Im1lbGxvIiwiaWRlbXBvdGVuY3lLZXkiOiJJSzJlOTY5OWU0LWQ0MTktNDcxNC04MGQxLTRhNmY0MWNmYzBhNCIsInN1YnRvdGFsIjp7ImN1cnJlbmN5IjoiVVNEIiwiY2VudHMiOjUwMH0sImlhdCI6MTc2MTkyODg0OCwiZXhwIjoxNzYxOTMwNjQ4fQ.h0wJcxejGhTOk5B8L9tvq5kymmRzwbxoR95wD3Ss_rE"}
         />
       </div>
     );
   }
   export default App;

Checkout Link Example

1. Get Checkout link

   curl --request POST \
        --url https://api-sandbox.coinflow.cash/api/checkout/link \
        --header 'Authorization: YOUR_API_KEY' \
        --header 'accept: application/json' \
        --header 'content-type: application/json' \
        --header 'x-coinflow-auth-user-id: user123' \
        --data '
   {
     "subtotal": {
       "currency": "USD",
       "cents": 200
     }
   }
   '

   {
     "link": "https://sandbox.coinflow.cash/purchase-v2/mello?sessionKey=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoidXNlcjEyMyIsIm1lcmNoYW50SWQiOiJtZWxsbyIsImlhdCI6MTc2MTkzMDEzMywiZXhwIjoxNzYyMDE2NTMzfQ.qfQCvvbUhwhzduMPGNrSRRPCOcVHNnRpLWlaSS27QRc&cents=200&currency=USD&useHeightChange=true&jwtToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoi456C4oKW26LXguCrgOaMgeGgg-iEquSEjOCngNmsya3piIjigKPDjMaw5YWA7rCB44eQ5rmk2aXnmbbmiIDjkKDUsN2g6ICT6IGPXHUwMDBlXFzQkMip6amP5aG06qCT6pyN6IiA4rK544Sl5qaB6bCky6Lml4fhio7oqazphrDqnrfVjNCH5puC6IaO6quX446x462p6Y-j5oeC4oCy5oCh7YOo6oWQ4K-i4omo44Cx6YCJ6Y2h64Oh6YCQ7qqZ66Cg44CjXHVkOTkx7YqU0LLrg6niiqDigapcdWRhN2HugLLtiaHurqbkl4DgpZDqhqDhgKHlj6DqhavvmrTqhpLmiaDgo5XjpKPmgIjihbjlgJDogILvpIAiLCJtZXJjaGFudElkIjoibWVsbG8iLCJpZGVtcG90ZW5jeUtleSI6IklLZDQ1MjBiOGItZjc5ZS00MDUxLWI2MjktNDIyMDEwODljYTZiIiwic3VidG90YWwiOnsiY3VycmVuY3kiOiJVU0QiLCJjZW50cyI6MjAwfSwiaWF0IjoxNzYxOTMwMTMzLCJleHAiOjE3NjE5MzE5MzN9.bF2RY44s6EutcrTazVnmLgmmXbZvfMNjAp7tmpZ5NX0"
   }
2. Embed checkout link in iframe or webview
   React Example

   import React from "react";
   export default function App() {
     return (
       <div style={{ width: "100%", height: "100vh"}}>
         <iframe
           src="https://sandbox.coinflow.cash/purchase-v2/mello?sessionKey=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoidXNlcjEyMyIsIm1lcmNoYW50SWQiOiJtZWxsbyIsImlhdCI6MTc2MTkzMDEzMywiZXhwIjoxNzYyMDE2NTMzfQ.qfQCvvbUhwhzduMPGNrSRRPCOcVHNnRpLWlaSS27QRc&cents=200&currency=USD&useHeightChange=true&jwtToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoi456C4oKW26LXguCrgOaMgeGgg-iEquSEjOCngNmsya3piIjigKPDjMaw5YWA7rCB44eQ5rmk2aXnmbbmiIDjkKDUsN2g6ICT6IGPXHUwMDBlXFzQkMip6amP5aG06qCT6pyN6IiA4rK544Sl5qaB6bCky6Lml4fhio7oqazphrDqnrfVjNCH5puC6IaO6quX446x462p6Y-j5oeC4oCy5oCh7YOo6oWQ4K-i4omo44Cx6YCJ6Y2h64Oh6YCQ7qqZ66Cg44CjXHVkOTkx7YqU0LLrg6niiqDigapcdWRhN2HugLLtiaHurqbkl4DgpZDqhqDhgKHlj6DqhavvmrTqhpLmiaDgo5XjpKPmgIjihbjlgJDogILvpIAiLCJtZXJjaGFudElkIjoibWVsbG8iLCJpZGVtcG90ZW5jeUtleSI6IklLZDQ1MjBiOGItZjc5ZS00MDUxLWI2MjktNDIyMDEwODljYTZiIiwic3VidG90YWwiOnsiY3VycmVuY3kiOiJVU0QiLCJjZW50cyI6MjAwfSwiaWF0IjoxNzYxOTMwMTMzLCJleHAiOjE3NjE5MzE5MzN9.bF2RY44s6EutcrTazVnmLgmmXbZvfMNjAp7tmpZ5NX0"
           allow="payment; fullscreen"
         />
       </div>
     );
   }

   React Native Example

   import React from "react";
   import { SafeAreaView, StyleSheet } from "react-native";
   import { WebView } from "react-native-webview";
   export default function CoinflowWebView() {
     return (
       <SafeAreaView style={styles.container}>
         <WebView
           source={{
             uri: "https://sandbox.coinflow.cash/purchase-v2/mello?sessionKey=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcklkIjoidXNlcjEyMyIsIm1lcmNoYW50SWQiOiJtZWxsbyIsImlhdCI6MTc2MTkzMDEzMywiZXhwIjoxNzYyMDE2NTMzfQ.qfQCvvbUhwhzduMPGNrSRRPCOcVHNnRpLWlaSS27QRc&cents=200&currency=USD&useHeightChange=true&jwtToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoi456C4oKW26LXguCrgOaMgeGgg-iEquSEjOCngNmsya3piIjigKPDjMaw5YWA7rCB44eQ5rmk2aXnmbbmiIDjkKDUsN2g6ICT6IGPXHUwMDBlXFzQkMip6amP5aG06qCT6pyN6IiA4rK544Sl5qaB6bCky6Lml4fhio7oqazphrDqnrfVjNCH5puC6IaO6quX446x462p6Y-j5oeC4oCy5oCh7YOo6oWQ4K-i4omo44Cx6YCJ6Y2h64Oh6YCQ7qqZ66Cg44CjXHVkOTkx7YqU0LLrg6niiqDigapcdWRhN2HugLLtiaHurqbkl4DgpZDqhqDhgKHlj6DqhavvmrTqhpLmiaDgo5XjpKPmgIjihbjlgJDogILvpIAiLCJtZXJjaGFudElkIjoibWVsbG8iLCJpZGVtcG90ZW5jeUtleSI6IklLZDQ1MjBiOGItZjc5ZS00MDUxLWI2MjktNDIyMDEwODljYTZiIiwic3VidG90YWwiOnsiY3VycmVuY3kiOiJVU0QiLCJjZW50cyI6MjAwfSwiaWF0IjoxNzYxOTMwMTMzLCJleHAiOjE3NjE5MzE5MzN9.bF2RY44s6EutcrTazVnmLgmmXbZvfMNjAp7tmpZ5NX0"
           }}
           style={{ flex: 1 }}
         />
       </SafeAreaView>
     );
   }
   const styles = StyleSheet.create({
     container: {
       flex: 1,
     },
   });