Fulfill Payment Intent

POST 
/payment_intents/:id/fulfill

Complete a payment intent from the browser by submitting the payment source with the publishable key and the intent's client secret.

The response is identical to Create Payment — a fulfillment produces a normal payment, so initiated, paid and failed all behave the same way, including the 3D Secure challenge in source.transaction_url.

The intent's amount, currency, description and callback_url are applied from the intent itself. Any values you send for those fields are ignored, so the browser cannot change what your backend approved.

Fulfillment is single-use. The first request that passes authorization, validation and the client_secret check consumes the intent; a later request gets intent_not_fulfillable. A card decline still consumes the intent — retrying means creating a fresh intent.

Request

Path Parameters

id uuidrequired

ID of the payment intent to fulfill.

application/json

Body

required

client_secret ClientSecret (string)required

Possible values: Value must match regular expression ^pi_secret_

Single-use token that authorizes fulfillment of this intent. Pass it to your frontend and treat it as a credential — it is all a browser needs, alongside your publishable key, to create this one payment.

given_id string

A UUID (v4 is recommended) that you generate from your side and attach it with the fulfillment request to support idempotency.

It is going be the ID of the created payment.

source

object

required

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

oneOf

CreditCardRequest

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.

card_auth_id uuid

Reuse a standalone Moyasar authentication (card_auth) instead of running 3DS for this payment. The authentication must belong to the same account, be authenticated, unconsumed, and match the payment's card fingerprint, amount, and currency.

Standalone 3D Secure is enabled only for selected merchants. Providing this field disables Moyasar's own 3DS for the payment.

card_auth_data

object

Bring your own 3DS values obtained elsewhere instead of running Moyasar's 3DS for this payment.

Standalone 3D Secure is enabled only for selected merchants. Providing this field disables Moyasar's own 3DS for the payment.

provider stringrequired

Identifies where the 3DS data originated (e.g. the MPI or provider that produced it).

eci stringrequired

Electronic Commerce Indicator.

authentication_value stringrequired

The authentication value (CAVV / AAV), Base64 encoded.

ds_transaction_id stringrequired

Directory Server transaction ID.

version stringrequired

3DS protocol version.

transaction_status stringrequired

EMVCo transaction status.

auth_scheme string

Directory Server used (visa, mada, master).

acs_transaction_id string

ACS transaction ID.

ds_reference_number string

Directory Server reference number.

acs_reference_number string

ACS reference number.

CardTokenPaymentRequest

type stringrequired

Possible values: [token]

token stringrequired

Possible values: Value must match regular expression ^token_

cvc Cvc (string)

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

Controls if 3DS is used for the payment. The default is null and is set depending on the token status.

For active token, the value is set to false and for save_only token, the value is set to true.

manual boolean

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

ApplePayRequest

type stringrequired

Possible values: [applepay]

token string

The encrypted token payload.

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.

statement_descriptor string

Possible values: <= 255 characters

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

ApplePayDecryptTokenRequest

type stringrequired

Possible values: [applepay]

number DpanNumber (string)

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

The Device Primary Account Number (DPAN).

month integer

Possible values: >= 1 and <= 12

Card expiry month.

year integer

Possible values: >= 2000

Card expiry year.

cryptogram Cryptogram (string)

Possible values: non-empty and <= 64 characters

The network token cryptogram generated by the device wallet.

device_id DeviceId (string)

Possible values: >= 8 characters and <= 16 characters

A unique identifier assigned to the device or wallet.

last_four LastFourPanNumber (string)

Masked card number showing only last four digits.

eci EciIndicator (string)

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

The Electronic Commerce Indicator (ECI).

SamsungPayRequest

type stringrequired

Possible values: [samsungpay]

token string

The encrypted token payload.

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.

statement_descriptor string

Possible values: <= 255 characters

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

StcPayRequest

type stringrequired

Possible values: [stcpay]

mobile stringrequired

Possible values: Value must match regular expression $(0|(00|\+)?966)?(5\d{8})$

Valid Saudi Arabian mobile number in one of the following formats:

• 05xxxxxxxx
• +9665xxxxxxxx
• 009665xxxxxxxx

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.

metadata

object

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
invoice_id uuid

Invoice this payment pays, when the fulfillment settles an invoice.

apply_coupon boolean

A flag to control the coupon application. This key is required only if you don't want to apply the coupon. Otherwise, the coupon is going to be applied.

splits

object[]

Array [

amount integerrequired

can be any value that is not zero

recipient_id uuidrequired

A valid Entity, Platform or Beneficiary ID

reference string

Possible values: <= 255 characters

This can be used by the API user to add a reference for the split which will be shown in the settlement file

description string

Possible values: <= 255 characters

Human-readable text that descripes the split

fee_source boolean

Determine which split will be used to deduct processing fees.

refundable boolean

Default value: true

Indicate if the split should be reversed when refunding the payment.

]

Responses

201

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

metadata

object

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

source

object

required

Source response object

oneOf

CreditCardResponse

type stringrequired

Possible values: [creditcard]

company Company (string)required

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

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, unionpay]

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

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.

token stringrequired

Token that is created using this payment.

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, unionpay]

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

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.

token stringrequired

Token that is created using this payment.

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.

splits

object[]

This field is returned for entities created after 2025-10, if you need to recieve it, please contact support team.

Array [

amount integerrequired

can be any value that is not zero

recipient_type stringrequired

Possible values: [Entity, Platform, Beneficiary]

Split recipient type

recipient_id uuidrequired

Recipeint ID

reference string

Possible values: <= 255 characters

This is a reference added by the API user during payment creation.

description string

Possible values: <= 255 characters

This is a human-readable added by the API user during payment creation.

fee_source booleanrequired

Determine which split will be used to deduct processing fees.

refundable booleanrequired

Default value: true

Indicate if the split should be reversed when refunding the payment.

]

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": {},
  "splits": [
    {
      "amount": 100,
      "recipient_type": "Entity",
      "recipient_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "reference": "string",
      "description": "string",
      "fee_source": false,
      "refundable": true
    }
  ]
}

400

Business Error or validation error. In addition to the usual payment validation errors, type may be:

• invalid_client_secret — the client_secret is missing or does not match the intent.

• intent_not_fulfillable — the intent is already fulfilled, canceled, or expired.

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

Payment intent not found.

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