Claim letter

curl --request POST \
  --url https://aropay.aro.media/api/v1/transfer/letter/claim \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "claimCode": "7K3M-Q9TX-2ABF-H8RD-5CWN-VGP4-0J6Y",
  "walletId": "ckwlt0004abcd"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({claimCode: '7K3M-Q9TX-2ABF-H8RD-5CWN-VGP4-0J6Y', walletId: 'ckwlt0004abcd'})
};

fetch('https://aropay.aro.media/api/v1/transfer/letter/claim', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://aropay.aro.media/api/v1/transfer/letter/claim"

payload = {
    "claimCode": "7K3M-Q9TX-2ABF-H8RD-5CWN-VGP4-0J6Y",
    "walletId": "ckwlt0004abcd"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "ok": true,
  "data": {
    "letter": {
      "id": "cklet0001abcd",
      "status": "CLAIMED",
      "chainId": 11155111,
      "amount": "50.00",
      "token": "cAROUSD",
      "amountVisibility": "sealed",
      "memo": "Thanks for the referral",
      "recipient": {
        "name": "Jane Doe",
        "address": {
          "line1": "12 Adeola Odeku Street",
          "line2": "Victoria Island",
          "landmark": "Opposite Eko Hotel",
          "city": "Lagos",
          "region": "LA",
          "postal": null,
          "country": "NG",
          "countryName": "Nigeria"
        }
      },
      "isDomestic": false,
      "expiresAt": "2026-10-22T09:45:00.000Z",
      "sender": {
        "walletId": "ckwlt0001abcd",
        "address": "0x8Ba1f109551bD432803012645Ac136ddd64DBA72"
      },
      "claimCode": null,
      "claimUrl": null,
      "pdfUrl": "https://dev.aropay.aro.media/api/v1/transfer/letter/cklet0001abcd/pdf",
      "escrow": {
        "transactionId": "cktxn0005abcd",
        "txHash": "0x4d1e…",
        "explorerUrl": "https://sepolia.etherscan.io/tx/0x4d1e…",
        "status": "CONFIRMED",
        "verified": true
      },
      "claim": {
        "transactionId": "cktxn0006abcd",
        "txHash": "0x7b90…",
        "explorerUrl": "https://sepolia.etherscan.io/tx/0x7b90…",
        "status": "CONFIRMED",
        "verified": true,
        "claimedAt": "2026-09-19T14:20:44.000Z",
        "walletAddress": "0x52aE1b7c86D2f1e9021a1B4a9c3B8d55E37F9021"
      },
      "refund": null,
      "mail": {
        "provider": "lob",
        "providerId": "ltr_4868c3b5655f1f5c",
        "deliveryMethod": "tracked",
        "status": "processed",
        "trackingNumber": "9407300000000000000004",
        "expectedDeliveryDate": "2026-09-22",
        "mailedAt": "2026-09-07T10:02:11.000Z",
        "testMode": true
      },
      "needsReview": false,
      "error": null,
      "createdAt": "2026-09-07T09:45:00.000Z",
      "updatedAt": "2026-09-19T14:20:44.000Z"
    },
    "transaction": {
      "id": "cktxn0006abcd",
      "type": "LETTER_CLAIM",
      "status": "CONFIRMED",
      "chainId": 11155111,
      "amount": "50.00",
      "token": "cAROUSD",
      "txHash": "0x7b90…",
      "settlementTxHash": null,
      "explorerUrl": "https://sepolia.etherscan.io/tx/0x7b90…",
      "fromAddress": "0x1F2e3D4c5B6a79880716253443526170A1b2C3d4",
      "toAddress": "0x52aE1b7c86D2f1e9021a1B4a9c3B8d55E37F9021",
      "counterparty": "aro-mail escrow",
      "walletId": "ckwlt0004abcd",
      "error": null,
      "errorCode": null,
      "payout": null,
      "metadata": {
        "letterId": "cklet0001abcd",
        "leg": "claim"
      },
      "createdAt": "2026-09-19T14:20:20.000Z",
      "updatedAt": "2026-09-19T14:20:44.000Z"
    }
  }
}

Aro Mail

Claim letter

Redeem a claim code into one of your wallets (custodial or external): the escrow vault sends the letter’s cAROUSD to the wallet with a confidentialTransfer (LETTER_CLAIM), and the letter moves CLAIMING → CLAIMED once the receipt lands and the encrypted amount is verified. Returns the letter (sealed amount and memo now revealed) and the claim transaction.

Single-use and race-safe: the first claimant wins a guarded status flip; anyone else gets 409 already_claimed. Idempotent for the same claimant, who gets the existing claim back. Senders cannot claim their own letters (400 cannot_claim_own_letter); they void instead. If the release reverts or the vault cannot cover it, the letter returns to claimable (502 claim_failed / 503 escrow_vault_underfunded). If the release was broadcast but bookkeeping failed, the call returns 502 claim_unsettled: the letter stays CLAIMING for you, and calling claim again returns the in-progress claim once reconciliation lands.

Blocks up to ~20 s; a CLAIMING letter with a PENDING claim leg finishes on later reads. Limited to 10 attempts per 15 minutes per principal and IP, separately from the general write budget.

POST

transfer

letter

claim

Claim letter

curl --request POST \
  --url https://aropay.aro.media/api/v1/transfer/letter/claim \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "claimCode": "7K3M-Q9TX-2ABF-H8RD-5CWN-VGP4-0J6Y",
  "walletId": "ckwlt0004abcd"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({claimCode: '7K3M-Q9TX-2ABF-H8RD-5CWN-VGP4-0J6Y', walletId: 'ckwlt0004abcd'})
};

fetch('https://aropay.aro.media/api/v1/transfer/letter/claim', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://aropay.aro.media/api/v1/transfer/letter/claim"

payload = {
    "claimCode": "7K3M-Q9TX-2ABF-H8RD-5CWN-VGP4-0J6Y",
    "walletId": "ckwlt0004abcd"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "ok": true,
  "data": {
    "letter": {
      "id": "cklet0001abcd",
      "status": "CLAIMED",
      "chainId": 11155111,
      "amount": "50.00",
      "token": "cAROUSD",
      "amountVisibility": "sealed",
      "memo": "Thanks for the referral",
      "recipient": {
        "name": "Jane Doe",
        "address": {
          "line1": "12 Adeola Odeku Street",
          "line2": "Victoria Island",
          "landmark": "Opposite Eko Hotel",
          "city": "Lagos",
          "region": "LA",
          "postal": null,
          "country": "NG",
          "countryName": "Nigeria"
        }
      },
      "isDomestic": false,
      "expiresAt": "2026-10-22T09:45:00.000Z",
      "sender": {
        "walletId": "ckwlt0001abcd",
        "address": "0x8Ba1f109551bD432803012645Ac136ddd64DBA72"
      },
      "claimCode": null,
      "claimUrl": null,
      "pdfUrl": "https://dev.aropay.aro.media/api/v1/transfer/letter/cklet0001abcd/pdf",
      "escrow": {
        "transactionId": "cktxn0005abcd",
        "txHash": "0x4d1e…",
        "explorerUrl": "https://sepolia.etherscan.io/tx/0x4d1e…",
        "status": "CONFIRMED",
        "verified": true
      },
      "claim": {
        "transactionId": "cktxn0006abcd",
        "txHash": "0x7b90…",
        "explorerUrl": "https://sepolia.etherscan.io/tx/0x7b90…",
        "status": "CONFIRMED",
        "verified": true,
        "claimedAt": "2026-09-19T14:20:44.000Z",
        "walletAddress": "0x52aE1b7c86D2f1e9021a1B4a9c3B8d55E37F9021"
      },
      "refund": null,
      "mail": {
        "provider": "lob",
        "providerId": "ltr_4868c3b5655f1f5c",
        "deliveryMethod": "tracked",
        "status": "processed",
        "trackingNumber": "9407300000000000000004",
        "expectedDeliveryDate": "2026-09-22",
        "mailedAt": "2026-09-07T10:02:11.000Z",
        "testMode": true
      },
      "needsReview": false,
      "error": null,
      "createdAt": "2026-09-07T09:45:00.000Z",
      "updatedAt": "2026-09-19T14:20:44.000Z"
    },
    "transaction": {
      "id": "cktxn0006abcd",
      "type": "LETTER_CLAIM",
      "status": "CONFIRMED",
      "chainId": 11155111,
      "amount": "50.00",
      "token": "cAROUSD",
      "txHash": "0x7b90…",
      "settlementTxHash": null,
      "explorerUrl": "https://sepolia.etherscan.io/tx/0x7b90…",
      "fromAddress": "0x1F2e3D4c5B6a79880716253443526170A1b2C3d4",
      "toAddress": "0x52aE1b7c86D2f1e9021a1B4a9c3B8d55E37F9021",
      "counterparty": "aro-mail escrow",
      "walletId": "ckwlt0004abcd",
      "error": null,
      "errorCode": null,
      "payout": null,
      "metadata": {
        "letterId": "cklet0001abcd",
        "leg": "claim"
      },
      "createdAt": "2026-09-19T14:20:20.000Z",
      "updatedAt": "2026-09-19T14:20:44.000Z"
    }
  }
}

Authorizations

Authorization

string

header

default:aro_sk_your_key_here

required

AroPay API key, sent as Authorization: Bearer aro_sk_…. Created in the dashboard under Settings → API keys. Takes precedence over a session cookie when both are present.

Body

application/json

claimCode

string

required

The 28-character code from the letter, with or without dashes/spaces; case-insensitive.

Required string length: 1 - 64

walletId

string

required

One of your wallets (custodial or external) to receive the cAROUSD.

Response

The claimed letter and the release transaction.

any

required

data

object

required

Show child attributes

Using the API

Auth

Profile & security

API keys

Wallets

Balances

Money movement

Aro Mail

Transactions

Sandbox

Claim letter

Authorizations

Body

Response