Skip to main content
API docs by Redocly

Merchant API (2.0)

Download OpenAPI specification:Download

paymennt provides a collection of APIs that enable you to process and manage payments. Our APIs accept and return JSON in the HTTP body, and return standard HTTP response codes. You can consume the APIs directly using

your favorite HTTP/REST library or make use of one of our SDKs.

Introduction

Learn how to integrate our APIs into your application

API Basics

The paymennt API gives you access to pretty much all the features you can use on our dashboard and lets you extend them for use in your application. It strives to be RESTful and is organized around the main resources you would be interacting with - with a few notable exceptions.

Requests and Response

Both request body data and response data are formatted as JSON. Content type for responses will always be application/json. Generally, all responses will be in the following format:

{
  "success": [boolean], // true indicates a successful operation
  "elapsed": [number], // time spent server side processing the request
  "error": [string], // if success is false, this will indicate the error
  "result": [object] // the result of the operation
}

Checkout

API endpoints for checkout management.

Create web checkout

Authorizations:
(ApiKeyApiSecret)
Request Body schema: application/json
requestId
required
string

A unique Identifier for this request, can be used later to query the status on the checkout.

orderId
required
string

A merchant unique transaction ID for this checkout. This can be the order ID. Must match any reference shown to the user during checkout / order history.

currency
required
string

ISO 4217 Currency Code (3 letter currency code).

amount
required
number > 0

The amount customers must pay.

object (CheckoutRequestTotals)

Order totals

required
Array of objects (CheckoutRequestItem)

An array of the items associated with this order.

required
object (CheckoutCustomer)

Customer associated with this subscription

required
object (CheckoutAddress)

Delivery address

object (CheckoutAddress)

Delivery address

returnUrl
required
string

URL to redirect user to after a successful or failed payment.

branchId
integer <int64>

The paymennt branch ID associated with this checkout.

allowedPaymentMethods
Array of strings
Items Enum: "CARD" "VISA" "MASTERCARD" "AMEX" "UNIONPAY" "TABBY" "CAREEM_PAY" "POINTCHECKOUT"

Array containing payment methods to be available at the payment page. When left empty all available options will show. When provided the payment methods order in the payment page will follow the same order passed in this parameter.

defaultPaymentMethod
string
Enum: "CARD" "VISA" "MASTERCARD" "AMEX" "UNIONPAY" "TABBY" "CAREEM_PAY" "POINTCHECKOUT"

Active payment method when opening the payment page. When left empty the default for your account at paymennt will be used.

language
string [ 2 .. 3 ] characters

2 Letter ISO 639-1 language code, for viewing the payment page. When the language is not supported, the system will revert to the default.

Responses

Request samples

Content type
application/json
{
  • "requestId": "ORD-1234-r1",
  • "orderId": "ORD-1234",
  • "currency": "AED",
  • "amount": 100,
  • "totals": {
    },
  • "items": [
    ],
  • "customer": {
    },
  • "billingAddress": {
    },
  • "deliveryAddress": {
    },
  • "returnUrl": "https://shop.example.com/payment-redirect/",
  • "branchId": 0,
  • "allowedPaymentMethods": [
    ],
  • "defaultPaymentMethod": "CARD",
  • "language": "EN"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Create terminal(POS) checkout

Authorizations:
(ApiKeyApiSecret)
Request Body schema: application/json
requestId
required
string

A unique Identifier for this request, can be used later to query the status on the checkout.

orderId
required
string

A merchant unique transaction ID for this checkout. This can be the order ID. Must match any reference shown to the user during checkout / order history.

description
string

Description of the order.

currency
required
string

ISO 4217 Currency Code (3 letter currency code).

amount
required
number > 0

The amount customers must pay.

terminalId
required
string^[0-9]+$

Terminal(POS) device ID at paymennt database.

object (CheckoutRequestTotals)

Order totals

Array of objects (CheckoutRequestItem)

An array of the items associated with this order.

object (CheckoutCustomer)

Customer associated with this subscription

object (CheckoutAddress)

Delivery address

branchId
integer <int64>

The paymennt branch ID associated with this checkout.

allowedPaymentMethods
Array of strings
Items Enum: "CARD" "VISA" "MASTERCARD" "AMEX" "UNIONPAY" "TABBY" "CAREEM_PAY" "POINTCHECKOUT"

Array containing payment methods to be available at the payment page. When left empty all available options will show. When provided the payment methods order in the payment page will follow the same order passed in this parameter.

defaultPaymentMethod
string
Enum: "CARD" "VISA" "MASTERCARD" "AMEX" "UNIONPAY" "TABBY" "CAREEM_PAY" "POINTCHECKOUT"

Active payment method when opening the payment page. When left empty the default for your account at paymennt will be used.

language
string [ 2 .. 3 ] characters

2 Letter ISO 639-1 language code, for viewing the payment page. When the language is not supported, the system will revert to the default.

expiresIn
integer <int32>

Responses

Request samples

Content type
application/json
{
  • "requestId": "ORD-1234-r1",
  • "orderId": "ORD-1234",
  • "description": "string",
  • "currency": "AED",
  • "amount": 100,
  • "terminalId": "string",
  • "totals": {
    },
  • "items": [
    ],
  • "customer": {
    },
  • "billingAddress": {
    },
  • "branchId": 0,
  • "allowedPaymentMethods": [
    ],
  • "defaultPaymentMethod": "CARD",
  • "language": "EN",
  • "expiresIn": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Create QR checkout

Authorizations:
(ApiKeyApiSecret)
Request Body schema: application/json
requestId
required
string

A unique Identifier for this request, can be used later to query the status on the checkout.

orderId
required
string

A merchant unique transaction ID for this checkout. This can be the order ID. Must match any reference shown to the user during checkout / order history.

description
string

Description of the order.

currency
required
string

ISO 4217 Currency Code (3 letter currency code).

amount
required
number > 0

The amount customers must pay.

deviceReference
string

Merchant device reference, to be used by the merchant to indicate the source device of the checkout if more than one device is used to submit checkouts to paymennt.

qrSize
integer <int32> [ 64 .. 1024 ]
Default: 300

the size of the QR image in pixels.

object (CheckoutRequestTotals)

Order totals

Array of objects (CheckoutRequestItem)

An array of the items associated with this order.

object (CheckoutCustomer)

Customer associated with this subscription

object (CheckoutAddress)

Delivery address

branchId
integer <int64>

The paymennt branch ID associated with this checkout.

allowedPaymentMethods
Array of strings
Items Enum: "CARD" "VISA" "MASTERCARD" "AMEX" "UNIONPAY" "TABBY" "CAREEM_PAY" "POINTCHECKOUT"

Array containing payment methods to be available at the payment page. When left empty all available options will show. When provided the payment methods order in the payment page will follow the same order passed in this parameter.

defaultPaymentMethod
string
Enum: "CARD" "VISA" "MASTERCARD" "AMEX" "UNIONPAY" "TABBY" "CAREEM_PAY" "POINTCHECKOUT"

Active payment method when opening the payment page. When left empty the default for your account at paymennt will be used.

language
string [ 2 .. 3 ] characters

2 Letter ISO 639-1 language code, for viewing the payment page. When the language is not supported, the system will revert to the default.

expiresIn
integer <int32> [ 5 .. 10080 ]

Number of minutes the payment will remain available, after that the payment will expire..

Responses

Request samples

Content type
application/json
{
  • "requestId": "ORD-1234-r1",
  • "orderId": "ORD-1234",
  • "description": "string",
  • "currency": "AED",
  • "amount": 100,
  • "deviceReference": "string",
  • "qrSize": 600,
  • "totals": {
    },
  • "items": [
    ],
  • "customer": {
    },
  • "billingAddress": {
    },
  • "branchId": 0,
  • "allowedPaymentMethods": [
    ],
  • "defaultPaymentMethod": "CARD",
  • "language": "EN",
  • "expiresIn": 1440
}

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Create mobile checkout

Authorizations:
(ApiKeyApiSecret)
Request Body schema: application/json
requestId
required
string

A unique Identifier for this request, can be used later to query the status on the checkout.

orderId
required
string

A merchant unique transaction ID for this checkout. This can be the order ID. Must match any reference shown to the user during checkout / order history.

currency
required
string

ISO 4217 Currency Code (3 letter currency code).

amount
required
number > 0

The amount customers must pay.

object (CheckoutRequestTotals)

Order totals

required
Array of objects (CheckoutRequestItem)

An array of the items associated with this order.

required
object (CheckoutCustomer)

Customer associated with this subscription

required
object (CheckoutAddress)

Delivery address

object (CheckoutAddress)

Delivery address

branchId
integer <int64>

The paymennt branch ID associated with this checkout.

allowedPaymentMethods
Array of strings
Items Enum: "CARD" "VISA" "MASTERCARD" "AMEX" "UNIONPAY" "TABBY" "CAREEM_PAY" "POINTCHECKOUT"

Array containing payment methods to be available at the payment page. When left empty all available options will show. When provided the payment methods order in the payment page will follow the same order passed in this parameter.

defaultPaymentMethod
string
Enum: "CARD" "VISA" "MASTERCARD" "AMEX" "UNIONPAY" "TABBY" "CAREEM_PAY" "POINTCHECKOUT"

Active payment method when opening the payment page. When left empty the default for your account at paymennt will be used.

language
string [ 2 .. 3 ] characters

2 Letter ISO 639-1 language code, for viewing the payment page. When the language is not supported, the system will revert to the default.

Responses

Request samples

Content type
application/json
{
  • "requestId": "ORD-1234-r1",
  • "orderId": "ORD-1234",
  • "currency": "AED",
  • "amount": 100,
  • "totals": {
    },
  • "items": [
    ],
  • "customer": {
    },
  • "billingAddress": {
    },
  • "deliveryAddress": {
    },
  • "branchId": 0,
  • "allowedPaymentMethods": [
    ],
  • "defaultPaymentMethod": "CARD",
  • "language": "EN"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Search checkouts

Authorizations:
(ApiKeyApiSecret)
query Parameters
type
string
Enum: "QR" "WEB" "MOBILE" "LINK" "TERMINAL"

query by checkout type

requestId
string

query by requestId used when submitting checkout

orderId
string

query by orderId associated with checkout

status
Array of strings
Items Enum: "PENDING" "AUTHORIZED" "PENDING_CONFIRMATION" "PAID" "FAILED" "CANCELLED" "EXPIRED" "REFUNDED" "PARTIALLY_REFUNDED" "CHARGEBACK"

comma separated list of checkout statuses

customer.reference
string

query by customer reference Id

customer.email
string

query by customer email

customer.phone
string

query by customer phone number

afterId
integer

filter checkouts after the provided id

afterTimestamp
string

query checkouts created after specific date/time, date format is yyyy-mm-dd HH:MM:SS

page
number >= 0

page number, default is 0

size
number >= 1

page size, default is 20

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Get checkout by Id

Authorizations:
(ApiKeyApiSecret)
path Parameters
checkoutId
required
string

Checkout Id retrieved from paymennt API.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Resend pending checkout to treminal

Authorizations:
(ApiKeyApiSecret)
path Parameters
checkoutId
required
string

Checkout Id.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Cancel pending checkout

Authorizations:
(ApiKeyApiSecret)
path Parameters
checkoutId
required
string

Checkout Id.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Refund a checkout

Authorizations:
(ApiKeyApiSecret)
path Parameters
checkoutId
required
string
Example: 1686414183718160600

Checkout Id retrieved from paymennt API.

query Parameters
amount
required
number
Example: amount=1500

Refun amount.

currency
required
string = 3 characters
Example: currency=USD

Currency ISO code.

note
required
string
Example: note=Out of stock

Refund note.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Payment

API endpoints for payment management.

Create payment

Authorizations:
(ApiKeyApiSecret)
Request Body schema: application/json
required
StoredCardPaymentSource (object) or TokenPaymentSource (object)
checkoutId
string

Checkout Identifier on Paymennt.com database.

object (CheckoutPaymentRequest)

Checkout details, required if checkoutId is not provided.

validReturnUrl
boolean
validBillingAddress
boolean

Responses

Request samples

Content type
application/json
{
  • "source": {
    },
  • "checkoutId": "string",
  • "checkoutDetails": {
    },
  • "validReturnUrl": true,
  • "validBillingAddress": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Capture authorized payment

Authorizations:
(ApiKeyApiSecret)
path Parameters
paymentId
required
string

Payment Id retrieved from Paymennt.com API.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Get payment by Id

Authorizations:
(ApiKeyApiSecret)
path Parameters
paymentId
required
string

Payment Id retrieved from Paymennt.com API.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Branches

API endpoints for branch management.

Get branch by Id

Authorizations:
(ApiKeyApiSecret)
path Parameters
branchId
required
string

Branch Id.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Get branches

List all branches associated with merchant

Authorizations:
(ApiKeyApiSecret)
query Parameters
page
number >= 0

page number, default is 0

size
number >= 1

page size, default is 20

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create new branch

Authorizations:
(ApiKeyApiSecret)
Request Body schema: application/json
name
required
string

Branch name.

currency
required
string

Branch currency code, ISO 4217 Currency Code (3 letter currency code).

description
string

Short description of the branch.

Responses

Request samples

Content type
application/json
{
  • "name": "Main branch",
  • "currency": "Main branch",
  • "description": "Main branch"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Disable branch

Authorizations:
(ApiKeyApiSecret)
path Parameters
branchId
required
string

Branch Id.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Enable branch

Authorizations:
(ApiKeyApiSecret)
path Parameters
branchId
required
string

Branch Id.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Webhooks

API endpoints for webhook management.

Get webhook by Id

Authorizations:
(ApiKeyApiSecret)
path Parameters
webhookId
required
string

Webhook Id.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

List webhooks

List all webhooks associated with merchant

Authorizations:
(ApiKeyApiSecret)
query Parameters
page
number >= 0

page number, default is 0

size
number >= 1

page size, default is 20

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create new webhook

Authorizations:
(ApiKeyApiSecret)
Request Body schema: application/json
address
required
string

Webhook endpoint that paymennt server will push messages to.

Responses

Request samples

Content type
application/json
{
  • "address": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Test webhook

Make a test call for the address associated with the webhook.

Authorizations:
(ApiKeyApiSecret)
path Parameters
webhookId
required
string

Webhook Id.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Disable webhook.

Authorizations:
(ApiKeyApiSecret)
path Parameters
webhookId
required
string

Webhook Id.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Enable webhook.

Authorizations:
(ApiKeyApiSecret)
path Parameters
webhookId
required
string

Webhook Id.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Delete webhook.

Authorizations:
(ApiKeyApiSecret)
path Parameters
webhookId
required
string

Webhook Id.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Terminals

API endpoints for terminal device management.

List termials

List all termials associated with the merchant account

Authorizations:
(ApiKeyApiSecret)
query Parameters
page
number >= 0

page number, default is 0

size
number >= 1

page size, default is 20

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get terminal device by Id

Authorizations:
(ApiKeyApiSecret)
path Parameters
terminalId
required
string

Terminal Id.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Stored Cards

API endpoints for managing stored cards.

List customer stored cards

Authorizations:
(ApiKeyApiSecret)
query Parameters
customerReferenceId
required
string

Customer ID at merchant suystem (Customer reference ID)

page
number >= 0

page number, default is 0

size
number >= 1

page size, default is 20

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Delete stored card by token

Authorizations:
(ApiKeyApiSecret)
query Parameters
cardToken
required
string

Stored card token

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Get stored card by token

Authorizations:
(ApiKeyApiSecret)
query Parameters
cardToken
required
string

Stored card token

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Customer subscription

API endpoints for Customer subscription management.

Search subscriptions

Authorizations:
(ApiKeyApiSecret)
query Parameters
status
Array of strings
Items Enum: "ACTIVE" "INACTIVE" "ARCHIVED" "EXPIRED"

comma separated list of subscription statuses

customer.reference
string

query by customer reference Id

customer.email
string

query by customer email

customer.phone
string

query by customer phone number

afterId
integer

filter subscriptions after the provided id

afterTimestamp
string

query subscriptions created after specific date/time, date format is yyyy-mm-dd HH:MM:SS

page
number >= 0

page number, default is 0

size
number >= 1

page size, default is 20

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Create subscription

Authorizations:
(ApiKeyApiSecret)
Request Body schema: application/json
description
required
string

Subscription decription

currency
required
string

ISO 4217 Currency Code (3 letter currency code) associated with this subscription.

amount
required
number

The grand total of the whole order. This is the amount the customer must pay.

object (CheckoutCustomer)

Customer associated with this subscription

object (CheckoutAddress)

Delivery address

object (CheckoutAddress)

Delivery address

customerId
integer <int64>

Customer id at paymennt database.

startDate
required
string <date>

The start date of the subscription in format (yyyy-MM-dd).

endDate
string <date>

The end date of the subscription in format (yyyy-MM-dd).

sendOnHour
required
integer <int32> [ 0 .. 23 ]

The hour of day in UTC the checkout will be created on

sendEvery
required
string
Enum: "DAY" "WEEK" "TWO_WEEKS" "MONTH" "TWO_MONTHS" "THREE_MONTHS" "SIX_MONTHS" "YEAR"

When to create the checkout

returnUrl
string

URL to redirect user to after a successful or failed payment.(Optional)

cancellationPolicyType
string
Enum: "Default" "Custom"

One of DEFAULT or CUSTOM

customCancellationTerms
string

Custom cancellation terms

Responses

Request samples

Content type
application/json
{
  • "description": "dozen of cookies",
  • "currency": "USD",
  • "amount": 1499.99,
  • "customer": {
    },
  • "billingAddress": {
    },
  • "deliveryAddress": {
    },
  • "customerId": 0,
  • "startDate": "2021-08-10",
  • "endDate": "2024-05-01",
  • "sendOnHour": 10,
  • "sendEvery": "TWO_MONTHS",
  • "returnUrl": "https://example.com/subscription/payment-check/",
  • "cancellationPolicyType": "DEFAULT",
  • "customCancellationTerms": "Cancellation allowed only 5 days before next billing date"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Get subscription by Id

Authorizations:
(ApiKeyApiSecret)
path Parameters
subscriptionId
required
string

Subscription Id retrieved from paymennt API.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Pause subscription

Authorizations:
(ApiKeyApiSecret)
path Parameters
subscriptionId
required
string

Subscription Id retrieved from paymennt API.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Resume subscription

Authorizations:
(ApiKeyApiSecret)
path Parameters
subscriptionId
required
string

Subscription Id retrieved from paymennt API.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}

Get subscription payments

Authorizations:
(ApiKeyApiSecret)
path Parameters
subscriptionId
required
string

Subscription Id retrieved from paymennt API.

query Parameters
page
number >= 0

page number, default is 0

size
number >= 1

page size, default is 20

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "elapsed": 12,
  • "result": {
    }
}