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

NameTypeDescription
merchant_keyMerchantKeyThe key of the merchant.
order_keyOrderKeyThe key of the order.
payment_idPaymentIdentifierThe payment identifier.

Parameters

Not applicable.

Request

FieldTypeMDescription
refund_referenceString(1, 35)OThe refund reference from the merchant.
descriptionString(1, 255)OThe description for the refund.
amountAmountOThe refund amount in minor units, e.g. in cents.
currencyCurrencyCThe refund amount currency.
Must be present if the refund amount is given.
refund_required_dateDateOThe date the refund must be captured.
userString(1, 255)OThe user who requested the refund and should be an email address.
itemsBlock[]OA list items to refund.
+ codeString(1, 50)MA code or article number identifying this item to refund.
+ quantityNumber(1, 2^30MQuantity of this item that's being refunded.

Response

Not applicable.

HTTP Status

StatusMeaning
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

NameTypeDescription
merchant_keyMerchantKeyThe key of the merchant.
order_keyOrderKeyThe key of the order.

Parameters

Not applicable.

Request

Not applicable.

Response

Array of:

FieldTypeMDescription
idPaymentIdentifierMThe payment identifier.
methodPaymentMethodMThe payment method, e.g. "IDEAL" or "SEPA_DIRECT_DEBIT".
amountAmountMThe authorized amount in minor units, e.g. in cents.
currencyCurrencyMThe authorized currency as ISO 4217 Alpha 3, e.g. "EUR".
partial_refund_allowedbooleanMTrue if the payment can be partially refunded, false otherwise.
refund_bank_account_requiredbooleanMTrue if the refund_bank_account is required in the refund request.

HTTP Status

StatusMeaning
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
        }
    ]'