Skip to content

    How to refund a payment

    In this how to we will perform a refund of paypal payment via curl. Refunds can only be applied on refund or capture transaction with the status __SUCCESS__.

    Request body

    We start with the body of the request:

    Request body

    {
      "initialAmount": 100,
      "currency": "EUR"
    }
    ParameterMandatoryDescription
    initialAmountmandatoryAmount as smallest currency unit e.g 100€ will be the result of `amount = 10000`
    currencymandatoryCurrency code according to ISO 4217

    Find more information in our API reference.

    Send request via curl

    With the body ready we can now send the request via curl.

    Curl - Request. Line breaks for readability

    curl \
    --user MerchantID:APIKey \
    -H "Content-Type: application/json" \
    -X POST \ 
    -d '{"initialAmount": 100,"currency": "EUR"}' \ https://apitest.payengine.de/v1/orders/{orderId}/transactions/{transactionId}/refund/

    curl command - descriptions

    We will now touch on every part of this command.

    --user MerchantID:APIKey Curl Option for HTTP basic access authentication.

    -H "Content-Type: application/json" content-type header "application/json" for our API.

    -X POST We want the request to be a HTTP POST.

    -d '{"initialAmount": 100,"currency": "EUR"}' The body for our request in JSON format.

    https://apitest.payengine.de/v1/orders/{orderId}/transactions/{transactionId}/refund/ The transactions refund endpoint of our API (Test in this case). Important: Prequisites need to be fullfilled for a successful refund transaction:

    • Refunds can only be applied to successful (status: SUCCESS) debit or capture transactions
    • We need the orderId, the orderId will be returned upon a successful debit or capture
    • We need the transactionId, the orderId will be returned upon a successful debit or capture

    curl command - response

    If the Request was successful we should get a response that looks like this:

    response

    {
        "createdAt": 1502096296617,
        "modifiedAt": 1502096298619,
        "type": "REFUND",
        "transactionId": "RefundTransaction-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "description": null,
        "initialAmount": 100,
        "currency": "EUR",
        "status": "SUCCESS",
        "order": {
            "createdAt": 1502092403541,
            "modifiedAt": 1502096298611,
            "merchantId": "Merchant-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "terms": null,
            "privacy": null,
            "orderId": "xxxxxxxxx",
            "merchantOrderId": "#0000000001",
            "paymentProviderTransactionId": null,
            "description": "Order at myshop.com",
            "statementDescription": null,
            "initialAmount": 100,
            "preauthorizedAmount": 0,
            "capturedAmount": 0,
            "refundedAmount": 0,
            "canceledAmount": 0,
            "currency": "EUR",
            "basket": [],
            "customer": {
                "createdAt": 1501757581860,
                "modifiedAt": 1501757581860,
                "email": "jane@doe.com",
                "merchantCustomerId": "xyz",
                "customerId": "Customer-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "addresses": [],
                "personas": [],
                "paymentInstruments": [
                    {
                        "paymentInstrumentId": "PaymentInstrument-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                        "merchantPaymentInstrumentId": null,
                        "attributes": null,
                        "encrypted": false,
                        "origin": "paypal",
                        "type": "paypal",
                        "recurring": false,
                        "createdAt": 1502092403535,
                        "modifiedAt": 1502092403535
                    }
                ]
            },
            "persona": null,
            "billingAddress": null,
            "shippingAddress": null,
            "ipAddress": null,
            "paymentInstrument": {
                "paymentInstrumentId": "PaymentInstrument-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "merchantPaymentInstrumentId": null,
                "attributes": null,
                "encrypted": false,
                "origin": "paypal",
                "type": "paypal",
                "recurring": false,
                "createdAt": 1502092403535,
                "modifiedAt": 1502092403535
            },
            "transactions": [
                {
                    "createdAt": 1502092403555,
                    "modifiedAt": 1502092403555,
                    "type": "DEBIT",
                    "transactionId": "DebitTransaction-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                    "description": "Order at myshop.com",
                    "initialAmount": 100,
                    "refundedAmount": 0,
                    "currency": "EUR",
                    "status": "SUCCESS",
                    "order": "xxxxxxxxx",
                    "parentTransaction": null,
                    "transactions": [
                        "RefundTransaction-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                    ],
                    "basket": []
                }
            ],
            "status": "OPEN",
            "channel": "ECOM",
            "source": null,
            "settled": null,
            "settlementDate": null,
            "allowedProducts": [],
            "product": "paypal",
            "transactionType": "DEBIT",
            "meta": null,
            "async": null,
            "redirectUrl": "https://apitest.payengine.de/order/paypal/1.0/redirect/Order-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
        },
        "parentTransaction": {
            "createdAt": 1502092403555,
            "modifiedAt": 1502092403555,
            "type": "DEBIT",
            "transactionId": "DebitTransaction-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "description": "Order at myshop.com",
            "initialAmount": 100,
            "refundedAmount": 0,
            "currency": "EUR",
            "status": "SUCCESS",
            "order": {
                "createdAt": 1502092403541,
                "modifiedAt": 1502096298611,
                "merchantId": "Merchant-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "terms": null,
                "privacy": null,
                "orderId": "xxxxxxxxx",
                "merchantOrderId": "#0000000001",
                "paymentProviderTransactionId": null,
                "description": "Order at myshop.com",
                "statementDescription": null,
                "initialAmount": 100,
                "preauthorizedAmount": 0,
                "capturedAmount": 0,
                "refundedAmount": 0,
                "canceledAmount": 0,
                "currency": "EUR",
                "basket": [],
                "customer": {
                    "createdAt": 1501757581860,
                    "modifiedAt": 1501757581860,
                    "email": "jane@doe.com",
                    "merchantCustomerId": "xyz",
                    "customerId": "Customer-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                    "addresses": [],
                    "personas": [],
                    "paymentInstruments": [
                        {
                            "paymentInstrumentId": "PaymentInstrument-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                            "merchantPaymentInstrumentId": null,
                            "attributes": null,
                            "encrypted": false,
                            "origin": "paypal",
                            "type": "paypal",
                            "recurring": false,
                            "createdAt": 1502092403535,
                            "modifiedAt": 1502092403535
                        }
                    ]
                },
                "persona": null,
                "billingAddress": null,
                "shippingAddress": null,
                "ipAddress": null,
                "paymentInstrument": {
                    "paymentInstrumentId": "PaymentInstrument-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                    "merchantPaymentInstrumentId": null,
                    "attributes": null,
                    "encrypted": false,
                    "origin": "paypal",
                    "type": "paypal",
                    "recurring": false,
                    "createdAt": 1502092403535,
                    "modifiedAt": 1502092403535
                },
                "transactions": [
                    "DebitTransaction-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                ],
                "status": "OPEN",
                "channel": "ECOM",
                "source": null,
                "settled": null,
                "settlementDate": null,
                "allowedProducts": [],
                "product": "paypal",
                "transactionType": "DEBIT",
                "meta": null,
                "async": null,
                "redirectUrl": "https://apitest.payengine.de/order/paypal/1.0/redirect/Order-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
            },
            "parentTransaction": null,
            "transactions": [
                "RefundTransaction-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
            ],
            "basket": []
        },
        "transactions": null,
        "basket": []
    }

    Find more information in our API reference.