purchase

POST 
/v1/orders/purchase

purchase

Request

application/json

Body

order_id uuidrequired
transaction_id uuidrequired
amount integerrequired

Possible values: >= 100

currency stringrequired

Possible values: <= 3 characters

description stringrequired

Possible values: <= 1024 characters

transaction_type stringrequired

Possible values: [internet, merchant, moto]

Default value: internet

sourceobjectrequired

oneOf

CardSource

type stringrequired

Possible values: [card]

number stringrequired

Possible values: Value must match regular expression ^[0-9]{13,19}$

month integerrequired

Possible values: >= 1 and <= 12

year integerrequired

Possible values: >= 2000

security_code string

Possible values: Value must match regular expression ^[0-9]{3,4}$

authobject

value stringrequired

Possible values: <= 256 characters

status stringrequired

Possible values: [Y, N, U, A, R]

eci stringrequired

Possible values: [00, 01, 02, 05, 06, 07]

version stringrequired

Possible values: [2.0.0, 2.1.0, 2.2.0, 2.3.0]

ds_transaction_id uuidrequired

acs_transaction_id uuidrequired

ds_reference_number stringrequired

Possible values: <= 32 characters

acs_reference_number stringrequired

Possible values: <= 32 characters

tds_purchase_date date-timerequired

ApplePaySource

type stringrequired

Possible values: [apple_pay]

number stringrequired

Possible values: Value must match regular expression ^[0-9]{13,19}$

month integerrequired

Possible values: >= 1 and <= 12

year integerrequired

Possible values: >= 2000

eci string

Possible values: [00, 01, 02, 05, 06, 07]

cryptogram string

Possible values: <= 256 characters

device_identifier string

GoogleSamsungPaySource

type stringrequired

Possible values: [google_pay, samsung_pay]

number stringrequired

Possible values: Value must match regular expression ^[0-9]{13,19}$

month integerrequired

Possible values: >= 1 and <= 12

year integerrequired

Possible values: >= 2000

eci string

Possible values: [00, 01, 02, 05, 06, 07]

cryptogram string

Possible values: <= 256 characters

deviceobjectrequired
user_agent stringrequired
Possible values: <= 1024 characters
ip_address ipv4required
airlineobject

reference string

Possible values: >= 6 characters and <= 15 characters, Value must match regular expression ^[a-zA-Z0-9]+$

new_agreementobject

type stringrequired

Possible values: [unscheduled, recurring, registered, installment]

id stringrequired

Possible values: non-empty and <= 36 characters, Value must match regular expression ^[a-zA-Z0-9-]+$

expiry date

max_use integer

Possible values: >= 1 and <= 999

variability string

Possible values: [fixed, variable]

Default value: variable

agreement_id string

Possible values: <= 64 characters

additional_dataobject

visaobject

authorization_characteristics_indicator string

Possible values: [I, P, R, Y]

market_specific_indicator string

Possible values: [A, B, E, H, J, M, N, T]

mastercardobject

transaction_type_indicator string

Possible values: [C01, C02, C03, C04, C05, C06, C07, C09, C51, C52, C53, C54, C55, C56, C57, C58, C59, C60, C61, C62, C63, C64, C65, C66, C67, C68, C91, C92, C93, C94, F07, F52, F53, F54, F61, F64, P01, P70, P71]

promotion_code string

Possible values: [ARGCTA, AGROF1, BNDES1, CHLCTA, COLCTA, GREECE, HGMINS, MCGARS, MCINST, MEXCTA, PARCEL, PERCTA, PHINST, PRYCTA, URYCTA]

sub_merchantobject
id stringrequired
Possible values: non-empty and <= 15 characters, Value must match regular expression ^[a-zA-Z0-9-]+$
registered_name stringrequired
Possible values: non-empty and <= 100 characters
trading_name stringrequired
Possible values: non-empty and <= 100 characters
email emailrequired

Responses

201

returns success

application/json

Schema

Schema

id string
merchantobject
id string
acquirer_id string
name string
arabic_name string
merchant_id string
rule_precedence string
currency string
amount integer
captured_amount integer
refunded_amount integer
voided_amount integer
description string
created_at string
updated_at string
sourceobject
type string
issuer nullable
card_type nullable
category nullable
country_alpha2 nullable
scheme string
first_digits string
last_digits string
month integer
year integer
reauthorized_order_id nullable
airline nullable
sub_merchant nullable
agreement nullable
transactionsobject[]

Array [

id string

status string

type string

source_type string

reverse_reason nullable

justification nullable

reversed_transaction_id nullable

message string

response_code string

retrieval_reference string

stan string

auth_code stringnullable

created_at string

amount integer

refunded_amount integer

]

Example (from schema)

{
  "id": "string",
  "merchant": {
    "id": "string",
    "acquirer_id": "string",
    "name": "string",
    "arabic_name": "string",
    "merchant_id": "string",
    "rule_precedence": "string"
  },
  "currency": "string",
  "amount": 0,
  "captured_amount": 0,
  "refunded_amount": 0,
  "voided_amount": 0,
  "description": "string",
  "created_at": "string",
  "updated_at": "string",
  "source": {
    "type": "string",
    "scheme": "string",
    "first_digits": "string",
    "last_digits": "string",
    "month": 0,
    "year": 0
  },
  "transactions": [
    {
      "id": "string",
      "status": "string",
      "type": "string",
      "source_type": "string",
      "message": "string",
      "response_code": "string",
      "retrieval_reference": "string",
      "stan": "string",
      "auth_code": "string",
      "created_at": "string",
      "amount": 0,
      "refunded_amount": 0
    }
  ]
}

Example

{
  "id": "05d7978d-ccb5-4116-8ca8-0ccfd54323fb",
  "merchant": {
    "id": "0191f5a7-3f84-75a8-8837-54e92f705716",
    "acquirer_id": "0191f5a7-3f82-7c1c-a419-d0434b450495",
    "name": "Merchant 10",
    "arabic_name": "الإسم العربي",
    "merchant_id": "60010",
    "rule_precedence": "merchant"
  },
  "currency": "SAR",
  "amount": 1000,
  "captured_amount": 1000,
  "refunded_amount": 0,
  "voided_amount": 0,
  "description": "Test Order",
  "created_at": "2024-09-15T12:27:44Z",
  "updated_at": "2024-09-15T12:27:44Z",
  "source": {
    "type": "card",
    "issuer": null,
    "card_type": null,
    "category": null,
    "country_alpha2": null,
    "scheme": "mastercard",
    "first_digits": "51234500",
    "last_digits": "0008",
    "month": 1,
    "year": 2039
  },
  "reauthorized_order_id": null,
  "airline": null,
  "sub_merchant": null,
  "agreement": null,
  "transactions": [
    {
      "id": "df3dbd59-cda8-4779-ae1d-4720b7145477",
      "status": "approved",
      "type": "purchase",
      "source_type": "moto",
      "reverse_reason": null,
      "justification": null,
      "reversed_transaction_id": null,
      "message": "APPROVED",
      "response_code": "00",
      "retrieval_reference": "242590000001",
      "stan": "000001",
      "auth_code": "486320",
      "amount": 1000,
      "refunded_amount": 0,
      "created_at": "2024-09-15T12:27:44Z"
    }
  ]
}

400

fails when retries are exhausted

application/json

Schema

Schema

message string

Example (from schema)

{
  "message": "string"
}

Example

{
  "message": "Initial request is still processing."
}

401

returns unauthorized

application/json

Schema

Schema

message string

Example (from schema)

{
  "message": "string"
}

Example

{
  "message": "Missing authentication information"
}

403

returns forbidden

application/json

Schema

Schema

message string

Example (from schema)

{
  "message": "string"
}

Example

{
  "message": "Unauthorized"
}

422

returns unprocessable_entity

application/json

Schema

Schema

message string
errorsobject
amount string[]
currency string[]
description string[]
source string[]
source.type string[]
device string[]
device.user_agent string[]
device.ip_address string[]

Example (from schema)

{
  "message": "string",
  "errors": {
    "amount": [
      "string"
    ],
    "currency": [
      "string"
    ],
    "description": [
      "string"
    ],
    "source": [
      "string"
    ],
    "source.type": [
      "string"
    ],
    "device": [
      "string"
    ],
    "device.user_agent": [
      "string"
    ],
    "device.ip_address": [
      "string"
    ]
  }
}

Example

{
  "message": "Data validation failed",
  "errors": {
    "amount": [
      "The value must be greater than or equal to 100."
    ],
    "currency": [
      "This field is missing."
    ],
    "description": [
      "This field is missing."
    ],
    "source": [
      "This field is missing."
    ],
    "source.type": [
      "This field is missing."
    ],
    "device": [
      "This field is missing."
    ],
    "device.user_agent": [
      "This field is missing."
    ],
    "device.ip_address": [
      "This field is missing."
    ]
  }
}

503

returns service_unavailable if tokenization fails

application/json

Schema

Schema

message string

Example (from schema)

{
  "message": "string"
}

Example

{
  "message": "Tokenization::Errors::SpgVaultError"
}

Loading...