Request Refund - Zid Docs

When a refund is requested from a customer the following request will be sent to the payment provider From ZidPay, if this is a success then a refund webhook should be sent to ZidPay

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" }'

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

Examples

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