Transfer refunds
API reference for refunding transfers
Refunds | |
---|---|
/transfer/refund/create | Create a refund for a transfer |
/transfer/refund/cancel | Cancel a refund |
/transfer/refund/get | Retrieve information about a refund |
/transfer/refund/create
Create a refund
Use the /transfer/refund/create
endpoint to create a refund for a transfer. A transfer can be refunded if the transfer was initiated in the past 180 days.
Processing of the refund will not occur until at least 4 business days following the transfer's settlement date, plus any hold/settlement delays. This 3-day window helps better protect your business from regular ACH returns. Consumer initiated returns (unauthorized returns) could still happen for about 60 days from the settlement date. If the original transfer is canceled, returned or failed, all pending refunds will automatically be canceled. Processed refunds cannot be revoked.
client_id
client_id
. The client_id
is required and may be provided either in the PLAID-CLIENT-ID
header or as part of a request body.secret
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.transfer_id
amount
idempotency_key
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a refund fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single refund is created.
50
1const request: TransferRefundCreateRequest = {2 transfer_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',3 amount: '12.34',4 idempotency_key: 'VEK2ea3X6LKywsc8J6pg',5};67try {8 const response = await client.transferRefundCreate(request);9} catch (error) {10 // handle error11}
Response fields and example
refund
id
transfer_id
amount
status
pending
: A new refund was created; it is in the pending state.
posted
: The refund has been successfully submitted to the payment network.
settled
: Credits have been refunded to the Plaid linked account.
cancelled
: The refund was cancelled by the client.
failed
: The refund has failed.
returned
: The refund was returned.pending
, posted
, cancelled
, failed
, settled
, returned
failure_reason
"failed"
or "returned"
. Null value otherwise.ach_return_code
R01
. A return code will be provided if and only if the refund status is returned
. For a full listing of ACH return codes, see Transfer errors.description
ledger_id
created
2006-01-02T15:04:05Z
date-time
network_trace_id
For
ach
or same-day-ach
transfers, this is the ACH trace number.
For rtp
transfers, this is the Transaction Identification number.
For wire
transfers, this is the IMAD (Input Message Accountability Data) number.request_id
1{2 "refund": {3 "id": "667af684-9ee1-4f5f-862a-633ec4c545cc",4 "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",5 "amount": "12.34",6 "status": "pending",7 "created": "2020-08-06T17:27:15Z",8 "failure_reason": null,9 "network_trace_id": null10 },11 "request_id": "saKrIBuEB9qJZno"12}
Was this helpful?
/transfer/refund/cancel
Cancel a refund
Use the /transfer/refund/cancel
endpoint to cancel a refund. A refund is eligible for cancellation if it has not yet been submitted to the payment network.
client_id
client_id
. The client_id
is required and may be provided either in the PLAID-CLIENT-ID
header or as part of a request body.secret
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.refund_id
1const request: TransferRefundCancelRequest = {2 refund_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',3};45try {6 const response = await client.transferRefundCancel(request);7} catch (error) {8 // handle error9}
Response fields and example
request_id
1{2 "request_id": "saKrIBuEB9qJZno"3}
Was this helpful?
/transfer/refund/get
Retrieve a refund
The /transfer/refund/get
endpoint fetches information about the refund corresponding to the given refund_id
.
client_id
client_id
. The client_id
is required and may be provided either in the PLAID-CLIENT-ID
header or as part of a request body.secret
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.refund_id
1const request: TransferRefundGetRequest = {2 refund_id: '460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9',3};45try {6 const response = await client.transferRefundGet(request);7} catch (error) {8 // handle error9}
Response fields and example
refund
id
transfer_id
amount
status
pending
: A new refund was created; it is in the pending state.
posted
: The refund has been successfully submitted to the payment network.
settled
: Credits have been refunded to the Plaid linked account.
cancelled
: The refund was cancelled by the client.
failed
: The refund has failed.
returned
: The refund was returned.pending
, posted
, cancelled
, failed
, settled
, returned
failure_reason
"failed"
or "returned"
. Null value otherwise.ach_return_code
R01
. A return code will be provided if and only if the refund status is returned
. For a full listing of ACH return codes, see Transfer errors.description
ledger_id
created
2006-01-02T15:04:05Z
date-time
network_trace_id
For
ach
or same-day-ach
transfers, this is the ACH trace number.
For rtp
transfers, this is the Transaction Identification number.
For wire
transfers, this is the IMAD (Input Message Accountability Data) number.request_id
1{2 "refund": {3 "id": "667af684-9ee1-4f5f-862a-633ec4c545cc",4 "transfer_id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",5 "amount": "12.34",6 "status": "pending",7 "created": "2020-08-06T17:27:15Z",8 "failure_reason": null,9 "network_trace_id": null10 },11 "request_id": "saKrIBuEB9qJZno"12}