Execute Payment Request

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 executing a payment via ZidPay to the payment provider.

metadata

object

optional

Optional metadata for logging purposes only. This does not affect payment processing.

Example:

{"PaymentReferenceId":"98bbb6fb-bbd7-41cb-8d5f-f8854b13c9b1"}

amount

integer

required

Total payment amount in Halala (1 SAR = 100 Halalas).

Example:

24900

currency

string

required

Currency code in ISO 4217 format.

Example:

SAR

callbackUrl

string

required

The URL to which the provider should redirect or send confirmation after a successful payment.

Example:

https://zidpay.org/api/payment/98bbb6fb-bbd7-41cb-8d5f-f8854b13c9b1/ThirdPartyCallback

errorUrl

string

required

The URL to which the provider should redirect or notify in case of payment failure.

Example:

https://zidpay.org/api/payment/98bbb6fb-bbd7-41cb-8d5f-f8854b13c9b1/ThirdPartyCallbackError

source

object

SourceDto

required

Contains the token type and value for processing the payment.

type

enum<string>

required

Type of token being used for the transaction.

Allowed values:

tokenapplepay

Example:

token

string

required

The actual token value obtained from direct, embedded, or Apple Pay flow.

Example:

tok_1Hh1XYZabc123456

Example

{
    "amount": 24900,
    "currency": "SAR",
    "callbackUrl": "https://zidpay.org/api/payment/98bbb6fb-bbd7-41cb-8d5f-f8854b13c9b1/ThirdPartyCallback",
    "errorUrl": "https://zidpay.org/api/payment/98bbb6fb-bbd7-41cb-8d5f-f8854b13c9b1/ThirdPartyCallbackr",
    "source": {
        "type": "token",
        "token": "###"
    },
    "metadata": {
        "PaymentReferenceId": "98bbb6fb-bbd7-41cb-8d5f-f8854b13c9b1"
    }
}

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/payments' \
--header 'Authorization: Authorization: Basic secret_key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 24900,
    "currency": "SAR",
    "callbackUrl": "https://zidpay.org/api/payment/98bbb6fb-bbd7-41cb-8d5f-f8854b13c9b1/ThirdPartyCallback",
    "errorUrl": "https://zidpay.org/api/payment/98bbb6fb-bbd7-41cb-8d5f-f8854b13c9b1/ThirdPartyCallbackr",
    "source": {
        "type": "token",
        "token": "###"
    },
    "metadata": {
        "PaymentReferenceId": "98bbb6fb-bbd7-41cb-8d5f-f8854b13c9b1"
    }
}'

Responses

🟢200OK

application/json

Body

Response body returned by the payment provider after executing a payment request.

id

string

required

Payment ID assigned by the provider.

Example:

pay_abc123xyz789

status

enum<string>

required

Current payment status.

Allowed values:

paidpending

Example:

paid

amount

integer

required

The amount processed in Halala.

Example:

24900

currency

string

required

Currency code in ISO 4217 format.

Example:

SAR

transactionUrl

string

required

Redirect URL for 3D Secure authentication or additional payment steps.

Example:

https://secure.paymentprovider.com/3ds/redirect?txn_id=abc123

Example

{
    "id": "pay_abc123xyz789",
    "status": "paid",
    "amount": 24900,
    "currency": "SAR",
    "transactionUrl": "https://secure.paymentprovider.com/3ds/redirect?txn_id=abc123"
}

🟠400Bad Request