Refund a processed payment.

Refund an already processed payment

Starts a new refund for the given Order, Payment and Merchant.

POST /ps/api/public/v1/merchants/{merchant_key}/orders/{order_key}/payments/{payment_id}/refunds

Identifiers

Name	Type	Description
merchant_key	MerchantKey	The key of the merchant.
order_key	OrderKey	The key of the order.
payment_id	PaymentIdentifier	The payment identifier.

Parameters

Not applicable.

Request

Field	Type	M	Description
refund_reference	String(1, 35)	O	The refund reference from the merchant.
description	String(1, 255)	O	The description for the refund.
amount	Amount	O	The refund amount in minor units, e.g. in cents.
currency	Currency	C	The refund amount currency. Must be present if the refund amount is given.
refund_required_date	Date	O	The date the refund must be captured.
user	String(1, 255)	O	The user who requested the refund and should be an email address.
items	Block[]	O	A list items to refund.
+ code	String(1, 50)	M	A code or article number identifying this item to refund.
+ quantity	Number(1, 2^30	M	Quantity of this item that's being refunded.

Response

Not applicable.

HTTP Status

Status	Meaning
201 (Created)	The refund is successfully created.
400 (Bad Request)	The request was not valid. Examples: Currency is not provided when amount is provided OR payment is not yet captured, or (partial) refund not allowed on the route.
403 (Forbidden)	The merchant key is not allowed.
404 (Not Found)	The transaction key or the payment id not found.

Note:

Either amount or item must be present, as both are mutually exclusive.
If no amount is specified, then the full amount or the remaining amount of a payment is refunded.

Refund payment example where the refund amount is specified

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders/3B88E0EF13E37D6A56AE949AD9E56961/payments/pid2163179782t/refunds \
    -d '{
        "refund_reference": "refund-1",
        "description"     : "Refund a Payment",
        "amount"          : 1000,
        "currency"        : "EUR",
        "refund_required_date" : "2020-08-31"
    }'
 
< Http 201 Created

Refund payment example for a full refund

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders/3B88E0EF13E37D6A56AE949AD9E56961/payments/pid2163179782t/refunds \
    -d '{
        "refund_reference": "refund-1",
        "description"     : "Refund a Payment"
    }'
 
< Http 201 Created

Refund payment example for detailed items to be refunded.

If the items are specified, then the refund amount should not be specified, as the refund items and the refund amount are mutually exclusive.

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders/3B88E0EF13E37D6A56AE949AD9E56961/payments/pid2163179782t/refunds \
    -d '{
        "refund_reference": "refund-1",
        "description"     : "Refund a Payment",
        "items": [
            {
              "code": "9781741791570",
              "quantity": 2
            }
          ]
    }'
 
< Http 201 Created

Get refund details

Returns the refund details for all payments under a given order.

GET /ps/api/public/v1/merchants/{merchant_key}/orders/{order_key}/refunds

Identifiers

Name	Type	Description
merchant_key	MerchantKey	The key of the merchant.
order_key	OrderKey	The key of the order.

Parameters

Not applicable.

Request

Not applicable.

Response

Array of:

Field	Type	M	Description
id	PaymentIdentifier	M	The payment identifier.
method	PaymentMethod	M	The payment method, e.g. "IDEAL" or "SEPA_DIRECT_DEBIT".
amount	Amount	M	The authorized amount in minor units, e.g. in cents.
currency	Currency	M	The authorized currency as ISO 4217 Alpha 3, e.g. "EUR".
partial_refund_allowed	boolean	M	True if the payment can be partially refunded, false otherwise.
refund_bank_account_required	boolean	M	True if the refund_bank_account is required in the refund request.

HTTP Status

Status	Meaning
200 (OK)	Success.
401 (Unauthorized)	Authorization header missing or invalid.
403 (Forbidden)	The merchant key is not allowed.

Get all the payment refund details.

> curl \
    -X GET \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/orders/F1499C097FFA533D46FB05D52680AB9A/refunds
 
< Http 200 Ok
<    '[
        {
            "id"                           : "pid2163179782t",
            "method"                       : "SEPA_DIRECT_DEBIT",
            "amount"                       : 2220,
            "currency"                     : "EUR",
            "partial_refund_allowed"       : true,
            "refund_bank_account_required" : false
        }
    ]'