Update Payment

PUT 
/payments/:id

Update Payment

Request

Path Parameters

id uuidrequired

ID of the payment to update

application/json

Body

required

description string

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

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

200

Successful operation

application/json

Schema

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

CreditCardResponse

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.

ApplePayResponse

type stringrequired

Possible values: [applepay]

name string

Name will always be null for Apple Pay payments.

company Company (string)required

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

The scheme through which the payment is processed.

number LastFourPanNumber (string)required

Masked card number showing only last four digits.

dpan MaskedPanNumber (string)

Masked card number showing first six and last four digits.

gateway_id stringrequired

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

The xx part is different based on the payment source:

• Apple Pay: ap
• Samsung Pay: sp
• Google Pay: gp

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.

message stringrequired

Human readable string representing the transaction result.

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.

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.

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.

GooglePayResponse

type stringrequired

Possible values: [googlepay]

name string

Name will always be null for Apple Pay payments.

company Company (string)required

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

The scheme through which the payment is processed.

number LastFourPanNumber (string)required

Masked card number showing only last four digits.

dpan MaskedPanNumber (string)

Masked card number showing first six and last four digits.

gateway_id stringrequired

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

The xx part is different based on the payment source:

• Apple Pay: ap
• Samsung Pay: sp
• Google Pay: gp

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.

message stringrequired

Human readable string representing the transaction result.

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.

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.

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.

SamsungPayResponse

type stringrequired

Possible values: [samsungpay]

name string

Name will always be null for Apple Pay payments.

company Company (string)required

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

The scheme through which the payment is processed.

number LastFourPanNumber (string)required

Masked card number showing only last four digits.

dpan MaskedPanNumber (string)

Masked card number showing first six and last four digits.

gateway_id stringrequired

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

The xx part is different based on the payment source:

• Apple Pay: ap
• Samsung Pay: sp
• Google Pay: gp

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.

message stringrequired

Human readable string representing the transaction result.

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.

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.

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.

StcPayResponse

type stringrequired

Possible values: [stcpay]

mobile stringrequired

Mobile number used to authorize the STC Pay payment.

reference_number stringrequired

Authorization attempt reference number returned by the STC Pay service.

cashier string

Cashier identifier sent to STC Pay during request initiation. This will show in the merchant dashboard.

branch string

Branch identifier sent to STC Pay during request initiation. This will show in the merchant dashboard.

transaction_url uri

OTP challenge URL.

You must collect the OTP value from the user and make POST request to the URL returned here along with the OTP value in a parameter called: otp_value.

message string

Human readable string representing the transaction result.

Example (from schema)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "initiated",
  "amount": 100,
  "fee": 0,
  "currency": "SAR",
  "refunded": 0,
  "refunded_at": "Date and time when the payment was refunded.",
  "captured": 0,
  "captured_at": "Date and time when the payment was captured.",
  "voided_at": "Date and time when the payment was voided.",
  "description": "Kindle Whitepaper",
  "amount_format": "1.00 SAR",
  "fee_format": "0.00 SAR",
  "refunded_format": "0.00 SAR",
  "captured_format": "0.00 SAR",
  "invoice_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ip": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "callback_url": "https://example.com/checkout/payer-return",
  "created_at": "Date and time when the payment was created.",
  "updated_at": "Date and time when the payment was last updated.",
  "metadata": {
    "cart_id": "72e470a5-cbc4-47b3-a52a-e89fda6adb19",
    "customer_email": "[email protected]",
    "customer_id": "23432"
  },
  "source": {}
}

400

Business Error or validation error.

application/json

Schema

Schema

type string

Contains the error type

message string

Human readable error message for the error

errors object

Contains string-array pair representing a field and list of validation errors.

Example (from schema)

{
  "type": "invalid_request",
  "message": null,
  "errors": {
    "foo": "this is returned for validation errors only"
  }
}

401

Invalid authorization credentials

application/json

Schema

Schema

type string

Possible values: [authentication_error]

message string

Possible values: [Invalid authorization credentials]

errors object

Example (from schema)

{
  "type": "authentication_error",
  "message": "Invalid authorization credentials",
  "errors": null
}

403

Invalid authorization credentials

application/json

Schema

Schema

type string

Possible values: [api_error]

message string

Possible values: [User not authorized]

errors object

Example (from schema)

{
  "type": "api_error",
  "message": "User not authorized",
  "errors": null
}

404

Invalid authorization credentials

application/json

Schema

Schema

type string

Possible values: [record_not_found]

message string
errors object

Example (from schema)

{
  "type": "record_not_found",
  "message": "The <object type> record you were looking for was not found.",
  "errors": null
}

Loading...