Request Refund - Zid Docs

Request

Path Params

ProviderUrl

string

required

The base URL of the payment provider’s API. ZidPay will use this URL to send requests such as token generation, payment execution, refunds, and Apple Pay registration. This should point to the root domain or environment-specific endpoint provided by the payment provider.

Example:

https://api.paymentprovider.com

Header Params

Authorization

string

optional

All secured endpoints require an Authorization header using Basic Authentication. The value should be the secret key provided to the payment provider during integration.

Example:

Authorization: Basic secret_key

Body Params application/json

Request body for initiating a refund from ZidPay to the payment provider.

amount

integer

required

Refund amount in Halala (1 SAR = 100 Halalas).

Example:

5000

paymentId

string

required

The original payment ID assigned by the provider for which the refund is being requested.

Example:

pay_abc123xyz

Example

{
    "amount": 5000,
    "paymentId": "pay_abc123xyz"
}

Request samples

Shell

JavaScript

Java

Swift

Go

PHP

Python

HTTP

C

C#

Objective-C

Ruby

OCaml

Dart

R

curl --location --request POST 'https://api.paymentprovider.com/refund' \
--header 'Authorization: Authorization: Basic secret_key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 5000,
    "paymentId": "pay_abc123xyz"
}'

Responses

🟢200OK

application/json

Body

Response returned by the payment provider after processing a refund request.

refundId

string <uuid>

required

Unique refund ID generated by the payment provider.

Example:

9f4b5fa0-bd22-40e4-b3ad-e6742f37a102

refundReference

string <uuid>

required

Reference ID for the refund transaction, used for tracking.

Example:

f781d5fa-9e8d-49b5-92a2-37321d5c8c4f

status

enum<string>

required

Current status of the refund request.

Allowed values:

Refundedpendingfailed

Example:

Refunded

Example

{
    "refundId": "9f4b5fa0-bd22-40e4-b3ad-e6742f37a102",
    "refundReference": "f781d5fa-9e8d-49b5-92a2-37321d5c8c4f",
    "status": "Refunded"
}