POST
/
transactions
/
{transaction_id}
/
refunds
curl --request POST \
  --url https://api.mattildapayments.com/transactions/{transaction_id}/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
{
  "type": "refund",
  "id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
  "transaction_id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
  "payment_service_refund_id": "refund_xYqd43gySMtori",
  "status": "processing",
  "currency": "MXN",
  "amount": 1299,
  "created_at": "2013-07-16T19:23:00.000+00:00",
  "updated_at": "2013-07-16T19:23:00.000+00:00",
  "target_type": "payment-method",
  "target_id": "c23ea83f-1b1c-4584-a0e8-78ef8c041949"
}

This endpoint requires the transactions.write scope.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
transaction_id
string
required

The ID for the transaction to get the information for.

Example:

"fe26475d-ec3e-4884-9553-f7356683f7f9"

Body

application/json

A request to refund a transaction.

​
amount
integer

The amount requested to refund.

If omitted, a full refund will be requested for the main payment method.

When set, the amount must be lower than or equal to the remaining balance in the associated transaction. Negative and zero-amount refunds are not supported.

Required range: 1 <= x <= 99999999
Example:

1299

​
target_type
enum<string> | null
default:payment-method

The target type to refund for. This can be used to target a gift card to refund to instead of the main payment method.

Available options:
payment-method,
gift-card-redemption
Example:

"gift-card-redemption"

​
target_id
string | null

The optional ID of the instrument to refund for. This is only required when the target_type is set to gift-card-redemption.

Example:

"c23ea83f-1b1c-4584-a0e8-78ef8c041949"

Response

201
application/json
Returns the created refund.

A refund record.

A refund is always associated with a single transaction, while a transaction can potentially have several refunds.

​
type
enum<string>

The type of this resource. Is always refund.

Available options:
refund
Example:

"refund"

​
id
string

The unique ID of the refund.

Example:

"8724fd24-5489-4a5d-90fd-0604df7d3b83"

​
transaction_id
string

The ID of the transaction associated with this refund.

Example:

"fe26475d-ec3e-4884-9553-f7356683f7f9"

​
payment_service_refund_id
string

The payment service's unique ID for the refund.

Example:

"refund_xYqd43gySMtori"

​
status
enum<string>

The status of the refund. It may change over time as asynchronous processing events occur.

  • processing - The refund is being processed.
  • succeeded - The refund was successful.
  • declined - The refund was declined by the underlying PSP.
  • failed - The refund could not proceed due to a technical issue.
  • voided - The refund was voided and will not proceed.
Available options:
processing,
succeeded,
declined,
failed,
voided
Example:

"processing"

​
currency
string

The currency code for this refund. Will always match that of the associated transaction.

Example:

"MXN"

​
amount
integer

The amount requested for this refund.

Required range: 0 <= x <= 99999999
Example:

1299

​
created_at
string

The date and time when this refund was created.

Example:

"2013-07-16T19:23:00.000+00:00"

​
updated_at
string

The date and time when this refund was last updated.

Example:

"2013-07-16T19:23:00.000+00:00"

​
target_type
enum<string>

The type of the instrument that was refunded.

Available options:
payment-method,
gift-card-redemption
Example:

"payment-method"

​
target_id
string | null

The optional ID of the instrument that was refunded. This may be null if the instrument was not stored.

Example:

"c23ea83f-1b1c-4584-a0e8-78ef8c041949"

Was this page helpful?

Suggest edits
List refundsRefund all instruments