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,
"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,
"metadata": {
"letterId": "cklet0001abcd",
"leg": "claim"
},
"createdAt": "2026-09-19T14:20:20.000Z",
"updatedAt": "2026-09-19T14:20:44.000Z"
}
}
}
Authorizations
apiKeyAuthsessionCookie
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