Skip to main content

Create Payment

POST 
/payments

Start a new Card, Apple Pay, Samsung Pay, Google Pay or STC Pay payment. The source object will define what payment is started.

When a payment is started, the status will be one of:

  • initiated
  • paid
  • failed

If the payment is initiated then you need to complete the payment transaction by completing the payment challenge found in source.transaction_url depending on the payment source type.

Request​

Body

required
    amount integerrequired

    A positive integer representing the payment amount in the smallest currency unit.

    Examples:

    • 1.00 SAR = 100
    • 1.00 KWD = 1000
    • 1 JPY = 1
    currency Currency (string)required

    ISO-4217 three-letter currency code.

    description string

    Human readable description for the payment. This is shown to the merchant only and is not shown to the payer.

    callback_url uri

    A valid URL that is used to return the payer back to the merchant website after card payment is done.

    This field is required when source.type is creditcard or token.

    sourceobjectrequired

    A payment source object to be charged, such as Apple Pay, Google Pay, Samsung Pay, Credit Card, Credit Card Token, or STC Pay source.

    oneOf

    type stringrequired

    Possible values: [creditcard]

    name stringrequired

    Possible values: <= 255 characters, Value must match regular expression ^[\w.-]+(?> [\w.-]+)+$

    Card holder name using English charactars. Must be two names at least.

    number PanNumber (string)required

    Possible values: Value must match regular expression ^\d{16,19}$

    The card number as a string without any separators.

    month integerrequired

    Possible values: >= 1 and <= 12

    Card expiry month.

    year integerrequired

    Possible values: >= 2000

    Card expiry year.

    cvc Cvc (string)required

    Possible values: >= 3 characters and <= 4 characters, Value must match regular expression ^\d{3,4}$

    The card security code. CVV for Visa, CVC for Mastercard or CSC for other brands. Must be 4 digits long for AMEX.

    statement_descriptor string

    Possible values: <= 255 characters

    Allows the merchant to add extra information to the statement descriptor sent to issuer.

    3ds boolean

    Default value: true

    Controls if 3DS is used for the payment.

    manual boolean

    Controls if the payment is authorized only without capturing. If the payment succeeds, the status will be set to authorized.

    save_card boolean

    If set to true, a token will be generated and returned along the payment response in source.token. This allows the merchant to use the token later for future payments.

    This requires Tokenization feature to be enabled for the merchant.

    metadataobject

    A set of key-value pairs where both key and value are strings. Metadata allows you to add more information to the object that will be returned later on in responses and webhook messages. Metadata is searchable using the Payment List API.

    property name* string

Responses​

Successful operation
Schema
    id uuidrequired
    status Status (string)required

    Possible values: [initiated, paid, authorized, failed, refunded, captured, voided, verified]

    Indicates the payment status.

    If the payment is in the initiated status, then an action must be taken (e.g. 3DS challenge) in order to complete the payment.

    The status authorized is used when a scheme payment is made with manual: true option which will cause the system to authorize the payment only without capturing it. The merchant must capture the payment within time it will be voided automatically by the issuer. Please note that when an issuer voids the payment, the status will be kept authorized and WILL NOT BE updated by the system.

    amount integerrequired
    fee integerrequired

    Estimated payment fee (including VAT).

    currency Currency (string)required

    ISO-4217 three-letter currency code.

    refunded integerrequired

    Refunded amount. Less than or equal to the payment amount.

    refunded_at timestamp
    captured integerrequired

    Captured amount. Less than or equal to the payment amount.

    captured_at timestamp
    voided_at timestamp
    description string
    amount_format stringrequired

    Formatted payment amount with currency

    fee_format stringrequired
    refunded_format stringrequired
    captured_format stringrequired
    invoice_id uuid

    Invoice ID that this payment is used to pay.

    ip uuidrequired

    Payer IPv4 address. This information is collected from the connection that has created the payment.

    You must ensure that the payment is created from the client device directly to ensure correct collection of the IP address.

    callback_url uri
    created_at timestamprequired
    updated_at timestamprequired
    metadataobject

    A set of key-value pairs where both key and value are strings. Metadata allows you to add more information to the object that will be returned later on in responses and webhook messages. Metadata is searchable using the Payment List API.

    property name* string
    sourceobjectrequired

    Source response object

    oneOf

    type stringrequired

    Possible values: [creditcard]

    company Company (string)required

    Possible values: [mada, visa, master, amex]

    The scheme through which the payment is processed.

    name stringrequired

    Card holder name

    number MaskedPanNumber (string)required

    Masked card number showing first six and last four digits.

    gateway_id stringrequired

    ID used for the backing acquirer gateway (MPG, MPGS or Cybersource).

    token stringrequired

    Token that is created using this payment.

    message stringrequired

    Human readable string representing the transaction result.

    transaction_url urirequired

    3D Secure challenge URL. Only returned when payment is initiated.

    reference_number RetrievalReferenceNumber (string)required

    Possible values: Value must match regular expression ^\d{12}$

    The RRN or retrieval reference number. This is a unique number for the transaction generated by the acquirer gateway and is sent to the issuer during the authorization process.

    This number is not unique across schemes (e.g. Visa and mada).

    This number can be useful in tracking the payment in the card holder account statement.

    authorization_code AuthorizationCode (string)

    Possible values: Value must match regular expression ^\d{6}$

    A six-digit number returned by the issuer in response to a successful authorization process.

    response_code ResponseCode (string)

    A two-digit string representing the authorization result (ISO 8583).

    Response code 00 indicates that the payment is approved by the issuer. Please refer to the response code table in the documentation for more information.

    issuer_name string

    Name of the card issuing bank. This name is inferred based on the card BIN or IIN.

    issuer_country string

    Origin country of the card issuer. A two-letter ISO 3166 code.

    issuer_card_type IssuerCardType (string)

    Possible values: [debit, credit, charge_card, unspecified]

    issuer_card_category IssuerCardCategory (string)

    Indicates the card category or product type, e.g., Platinum, Signature, etc.

    This field is a human readable text and does not have a defined set of values.

Loading...