Refunds
Non-custodial refunds: the payer claims, we screen, you send from your wallet
POST /v1/invoices/{id}/refunds
Create a refund for an invoice.
Returns the refund with its claim link. Send the payer claim_url (or a link carrying
claim_token): they choose the network and address, which we screen (OFAC SDN list and the token
issuer's blacklist). You then send the funds from your own wallet and record the transaction with
mark_sent. Tillsafe never holds or moves refund money.
Authentication: Secret key
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
idrequired | path | string | Invoice id (inv_…) |
Idempotency-Keyrequired | header | string | Unique per refund |
Request body
application/json
| Field | Type | Description |
|---|---|---|
amount | string or null | Whole tokens, as a decimal string. Defaults to the overpaid excess (or, for an
|
asset | string or null | The asset code to refund in. Defaults to the asset the invoice was paid in; give another received asset (e.g. a wrong token) to refund that.
|
reason | RefundReason or null |
Responses
| Status | Description | Body |
|---|---|---|
| 201 | Created | Refund application/json |
| 400 | ErrorResponse application/json | |
| 404 | ErrorResponse application/json | |
| 409 | Nothing (or not that much) is refundable | ErrorResponse application/json |
GET /v1/refunds
List refunds, newest first.
Authentication: Secret key
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
limit | query | integer (int32) | 1 to 100, default 10
|
cursor | query | string |
|
invoice | query | string | Only refunds of this invoice (inv_…) |
status | query | RefundStatus | Only refunds in this status |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | RefundList application/json | |
| 400 | ErrorResponse application/json |
GET /v1/refunds/{id}
Retrieve a refund.
Authentication: Secret key
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
idrequired | path | string | Refund id (rfd_…) |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Refund application/json | |
| 404 | ErrorResponse application/json |
POST /v1/refunds/{id}/cancel
Cancel a refund that has not been sent. Its claim link stops working.
Authentication: Secret key
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
idrequired | path | string | Refund id (rfd_…) |
Idempotency-Keyrequired | header | string | Unique per request |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Refund application/json | |
| 404 | ErrorResponse application/json | |
| 409 | Already sent | ErrorResponse application/json |
POST /v1/refunds/{id}/mark_sent
Record that you sent the refund.
Call this after your own wallet sent the payout to payout.address on payout.network. Only a
ready_to_send refund can be marked sent: an in_review one matched a screening list and must not be
paid.
Authentication: Secret key
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
idrequired | path | string | Refund id (rfd_…) |
Idempotency-Keyrequired | header | string | Unique per request |
Request body
application/json
| Field | Type | Description |
|---|---|---|
tx_hashrequired | string | Your payout transaction (0x + 64 hex digits; TRON hashes without 0x are accepted too). |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Refund application/json | |
| 404 | ErrorResponse application/json | |
| 409 | Not ready to send (unclaimed, in review, cancelled, ...) | ErrorResponse application/json |