Request refund

1. Create refund request

Create a RR. Send an HTTP POST request to the relevant endpoint + /api/v1/refunds/init including the headers Authorization: Bearer <payment_token>. You can use the same payment token generated previously. The RR body should contain an array of payments with paymentId and amount corresponding to each refund required.

Request

curl --location --request POST 'https://uat.app.payvyne.com/api/v1/refunds/init' \
--header 'Authorization: Bearer <payment_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "payments": [
        {
            "paymentId": "1ac613c7ca3eca52",
            "amount": 2.4,
            "idempotencyId": "b7be040e-59f1-4798-98e3-7c7dc6263bf4"
        },
        {
            "paymentId": "4d6fb61dd6eb0c7b",
            "amount": 9,
            "idempotencyId": "48522dfe-acbf-4d5e-9c9b-24393900d5a9"
        },
        {
            "paymentId": "2178e53c08b1f3f5",
            "amount": 0.1,
            "idempotencyId": "e0ae2ebb-2d06-4f77-9373-fe49d9cb53a4"
        },
        {
            "paymentId": "1ac613c7ca3eca52",
            "amount": 1.00,
            "idempotencyId": "fd373d7a-46d2-47a2-a46d-256b8b4964ed"
        },
        {
            "paymentId": "1a17fe039cd34777",
            "amount": 99999.99,
            "idempotencyId": "a0cc9b57-e2a7-46dc-90bb-dd4be4372c99"
        },
        {
            "paymentId": "4de89355d8fc67b0",
            "amount": 1,
            "idempotencyId": "cb3b2025-96f8-48ad-b0b1-75aafc8f2874"
        }
    ]
}'

payments

ParameterDescription
paymentId16 digit alphanumeric unique payment identifier.
amountThe amount to be refunded.
idempotencyIdA unique value, between 16 and 64 characters, which the resource server uses to recognise subsequent retries of the same request.

A successful RR returns a 202 response code and an object with refunds and/or errors arrays.

If something unexpected happened during the request, the API returns an error response with the appropriate HTTP status code and a JSON response that contains detailed information about the problem.

πŸ‘

Try it out

Unsuccessful refunds may be automatically reattempted before a failed status update is provided. Our API supports idempotency for safely retrying requests without accidentally performing the same operation twice. Read more about idempotent requests here.

Requests relating to separate payments should use a unique idempotencyId if the previous request with the same idempotencyId was successful (for example, in the case of multiple or partial refunds). If you send the same paymentId and idempotencyId, the response will contain details of the original request and a new request won't be created. A webhook notification is sent containing the final refund status. If a refund status is FAILED, make the request again with a new idempotencyId to retry the refund safely.

Response

{
    "refunds": [
        {
            "id": "1bd7805da16df89e",
            "status": "NEW",
            "amount": 2.4,
            "currency": "GBP",
            "paymentId": "1ac613c7ca3eca52"
        },
        {
            "id": "46713c3a44ad27f0",
            "status": "NEW",
            "amount": 0.1,
            "currency": "GBP",
            "paymentId": "2178e53c08b1f3f5"
        }
    ],
    "errors": [
        {
            "paymentId": "4d6fb61dd6eb0c7b",
            "errorMessage": "Payment is not in SETTLED or PART_REFUNDED status!"
        },
        {
            "paymentId": "1ac613c7ca3eca52",
            "errorMessage": "Multiple refunds cannot be made at the same time"
        },
        {
            "paymentId": "1a17fe039cd34777",
            "errorMessage": "The refund amount cannot be greater than the payment amount"
        },
        {
            "paymentId": "4de89355d8fc67b0",
            "errorMessage": "Could not find payment with ID=4de89355d8fc67b0"
          },
        {
            "paymentId": "2178e53c08b1f3f5",
            "errorMessage": "Insufficient funds for refund"
        }
    ]
}
ParameterDescription
refundsAn array of objects containing refunds that were initiated refunds successfully.
errorsArray of objects containing error details for refunds that could not be initiated.

refunds

ParameterDescription
id16 digit alphanumeric unique refund identifier.
statusThe current status of the refund. For all possible statuses see here.
amountThe amount of the refund.
currencyThe three-character refund currency using ISO 4217.
paymentId16 digit alphanumeric unique payment identifier (corresponding to that specified in the RR ).

errors

ParameterDescription
paymentId16 digit alphanumeric unique payment identifier (corresponding to that specified in the RR ).
errorMessageA short description explaining why the refund initiation failed.