CheckoutPayment ScenariosRefunds

Crypto Refunds

Once a crypto payment has successfully settled, you can programmatically issue a refund to your customer’s wallet. Refunds are processed on-chain, and you’ll receive a transaction hash that can be shared with the end user as proof of refund.

Before issuing a refund:

  • The original payment must be settled
  • You must have the paymentId
  • You must provide a valid destination wallet address

Step 1: Initiate a Refund

Send a PUT request to the refund endpoint with the desired refund details.

Request

$curl --location --request PUT 'https://api-sandbox.coinflow.cash/api/merchant/payments/{paymentId}/refund' \
>--header 'Authorization: coinflow_sandbox_11111111111111111111111111111111_11111111111111111111111111111111' \
>--header 'Content-Type: application/json' \
>--data '{
>  "refundReason": "userCancellation",
>  "destinationWallet": "123abcd",
>  "partialAmount": {
>    "cents": 200
>  }
>}'

Parameters

FieldTypeDescription
refundReasonstringReason for refund (e.g. userCancellation)
destinationWalletstringWallet address where funds will be sent
partialAmountobjectAmount to refund in cents (optional; omit for full refund)

Response

1"RefundPipeline{paymentId}"

This indicates the refund has been initiated and is being processed.

Step 2: Retrieve Payment Refund Details

To confirm the refund and retrieve on-chain details, fetch the payment by ID.

Request

$curl --location 'https://api-sandbox.coinflow.cash/api/merchant/payments/{paymentId}' \
>--header 'Authorization: coinflow_sandbox_11111111111111111111111111111111_11111111111111111111111111111111'

Step 3: Inspect Refund Data

Within the response, reference the following fields:

Full Example Response

1{
2  "_id": "69fa33f366fad13675d6c897",
3  "paymentId": "51e5ac49-d3ad-412c-afdb-acb1a5b50b3d",
4  "totals": {
5    "subtotal": { "cents": 300, "currency": "USD" },
6    "creditCardFees": { "cents": 2, "currency": "USD" },
7    "chargebackProtectionFees": { "cents": 0, "currency": "USD" },
8    "gasFees": { "cents": 0, "currency": "USD" },
9    "fxFees": { "cents": 0, "currency": "USD" },
10    "total": { "cents": 302, "currency": "USD" },
11    "merchantPaidCreditCardFees": { "cents": 0, "currency": "USD" },
12    "merchantPaidGasFees": { "cents": 0, "currency": "USD" },
13    "merchantPaidFxFees": { "cents": 0, "currency": "USD" }
14  },
15  "customer": "69fa33f366fad13675d6c894",
16  "merchant": "68dae987ec61c5361b320e50",
17  "webhookInfo": {
18    "item": "sword",
19    "email": ""
20  },
21  "chargebackProtectionDecision": "Not Enabled",
22  "cryptoInfo": {
23    "status": "REFUNDED",
24    "sessionId": "0f495375-1796-4d12-a3a2-07cc6563a23d",
25    "actualPaymentAmountUSD": "4.01196",
26    "blockchainLogoUrl": "https://static.paywithglide.xyz/logos/solana-7228edcd.png",
27    "originatingTransactionHash": "5xWjaoesF1SyRaz4vgX2jKmz6whsxWBAWqeKuvj46dPn9idbYTi7PvGzTa2iMUpY4poyK7G4CS6FSr1Zm1e1234",
28    "originatingWallet": "9rpv2W6qyShwcwTgZXpiFuC5kFGYpzhYugmpKK5L1234",
29    "paymentCurrency": "solana:103/token:111111111111111111111111111",
30    "sponsoredTransactionHash": "4JpcdKKjMi1MzM5fayUwncyfaN8CKEJgPzdGmoU2SF8UfKyn4N75HmhoxRmia8WZn7W5dk91T6ttcy9MM73TPKS9",
31    "tier": "stables",
32    "token": "USDC",
33    "tokenAmount": "4.01196",
34    "tokenLogoUrl": "https://static.buildwithglide.com/logos/usdc-8aaf5df7.png",
35    "refundAddress": "91eEM5xHu8tY82tiNkjzJNXGLM7NhyCEVaRhvs9p1234",
36    "refundTransactionHash": "2cboz1RP9H9nY5yhcSz3xCBfZhMXrkfWf4rZbKnmGAK42xWyuP6R66iTDc2AwFPSonKDGqycR9ZtpGnmy4qQ1234"
37  },
38  "settlementType": "USDC",
39  "blockchain": "solana",
40  "createdAt": "2026-05-05T18:16:19.342Z",
41  "updatedAt": "2026-05-05T18:19:44.138Z",
42  "refundInfo": {
43    "amount": { "cents": 200, "currency": "USD" },
44    "refundedAt": "2026-05-05T18:19:30.297Z",
45    "count": 1
46  }
47}

Step 4: Share Refund Receipt

Provide the cryptoInfo.refundTransactionHash to your customer.

  • This is the on-chain transaction hash
  • It can be used to verify the refund on a blockchain explorer
  • Acts as a proof of refund

Notes & Best Practices

  • Refunds are irreversible once submitted on-chain
  • Always validate the destinationWallet before initiating
  • Use partial refunds (partialAmount) when issuing refunds for a portion of the original payment
  • Monitor cryptoInfo.status to confirm refund completion (REFUNDED)