Get payment status

After receiving a callback or a webhook for a payment success ZidPay system will send a payment status request to payment provider to make sure the payment is actually successful.

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

Provider paymentId

string

required

A unique identifier assigned by the payment provider to each payment transaction. It is used by ZidPay to query the status of a specific payment or to initiate related actions such as refunds.

Example:

b7a1c6f2-9d3e-4e2c-bf1f-05e6a1c8f317

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

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/json

Body

Response returned by the provider when ZidPay queries the status of a specific payment.

string

required

Unique identifier of the payment transaction assigned by the provider.

Example:

pay_abc123xyz789

status

enum<string>

required

Current status of the payment.

Allowed values:

paidrefundedpendingfailed

Example:

paid

amount

integer

required

Total amount of the transaction in Halala.

Example:

24900

currency

string

required

Currency code in ISO 4217 format.

Example:

SAR

refunded

integer

optional

Amount refunded (in Halala), if any. Will be 0 if no refund has occurred.

Example:

errorCode

string

optional

Error code indicating reason for failure, if status is 'failed'.

Example:

ZDP001

Example

{
    "id": "pay_abc123xyz789",
    "status": "paid",
    "amount": 24900,
    "currency": "SAR",
    "refunded": 0,
    "errorCode": "ZDP001"
}

🟠422Parameter Error