Skip to main content

Create Invoice

POST 
/invoices

Create Invoice

Request​

Body

required
    amount Amount (integer)required

    Possible values: >= 100

    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 stringrequired

    An arbitrary string that you can attach to an invoice object. This may include a description of the merchandise or the service that your customer is billed for. The invoice description is displayed on the invoice alongside the amount when the invoice is presented to the user.

    callback_url uri

    An endpoint on your server that will get a POST request with the invoice object when the invoice is paid.

    Unlike Payment, this is not used to redirect the user, this is only used to send a notification.

    success_url uri

    An endpoint where the payer will be redirected to when the invoice is paid.

    back_url uri

    An endpoint on your site used for redirect when the user clicks on the back button.

    expired_at timestamp

    Specifies when the invoice will get expired.

    User will be prevented from paying the invoice once expired.

    The argument can be a date string (e.g. 2017-01-12) or datetime string (e.g. 2018-01-01T09:55:14.000Z) in ISO 8601 format (default is null).

    Specifying a date only will cause the time to be set to 00:00:00 which will cause the invoice to expire at the beginning of the day.

Responses​

Successful operation
Schema
    id uuid
    status InvoiceStatus (string)

    Possible values: [initiated, paid, failed, refunded, canceled, on_hold, expired, voided]

    amount integer
    currency Currency (string)

    ISO-4217 three-letter currency code.

    description string
    logo_url uri

    URL to the entity logo configured through Moyasar Dashboard

    amount_format string

    Formatted invoice amount with currency

    url uri

    URL for the checkout page that the merchant must present to the payer to pay the invoice.

    callback_url uri
    expired_at string
    created_at timestamp
    updated_at timestamp
    back_url uri
    success_url uri
    paymentsobject[]

    Payment attempts made against this invoice

  • Array [

    • 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.

  • ]

    • 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
Loading...