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

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

Parameter	Description
paymentId	16 digit alphanumeric unique payment identifier.
amount	The amount to be refunded.
idempotencyId	A 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

JSON

{
    "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"
        }
    ]
}

Parameter	Description
refunds	An array of objects containing refunds that were initiated refunds successfully.
errors	Array of objects containing error details for refunds that could not be initiated.

refunds

Parameter	Description
id	16 digit alphanumeric unique refund identifier.
status	The current status of the refund. For all possible statuses see here.
amount	The amount of the refund.
currency	The three-character refund currency using ISO 4217.
paymentId	16 digit alphanumeric unique payment identifier (corresponding to that specified in the RR ).

errors

Parameter	Description
paymentId	16 digit alphanumeric unique payment identifier (corresponding to that specified in the RR ).
errorMessage	A short description explaining why the refund initiation failed.