Credentialed Transactions Developer Guide {#credentials-about-guide} ==================================================================== This section describes how to use this developer guide and where to find further information. Audience and Purpose : This guide is written for application developers who want to use the `REST API` to integrate payment card processing using credentials into an order management system. Implementing the `Cybersource` payment services requires software development skills. You must write code that uses the API request and response fields to integrate the credit card services into your existing order management system. Visit the [`Cybersource` documentation hub](https://developer.cybersource.com/docs.md "") to find additional processor-specific versions of this guide and additional technical documentation. Convention : This statement appears in this document: > IMPORTANT > An *Important* statement contains information essential to successfully completing a task or learning a concept. Customer Support : For support information about any service, visit the Support Center: Recent Revisions to This Document {#credentials-doc-revisions} ============================================================== 26.04.01 -------- `National Payment Gateway` initial release. Introduction to Credentialed Transactions {#credentials-intro} ============================================================== Credentialed transactions, also known as credentials‑on‑file (COF) or card‑on‑file transactions, are payments that either store a customer's payment credentials for future use or use previously stored credentials to complete a transaction. All COF transactions begin with a customer-initiated transaction, in which the customer actively participates, such as a card‑present purchase, online checkout, or use of a stored credential. Benefits of Credentialed Transactions ------------------------------------- Merchants following the stored credentials framework experience these benefits: * Better visibility into transaction risk. * Improved authorization success rates. * A smoother customer experience. * Fewer disputes and customer complaints. * Use of Real Time Visa Account Updater for fresher card details. For more information on the stored credentials framework, see [Improving Authorization Management for Transactions with Stored Credentials](https://usa.visa.com/dam/VCOM/global/support-legal/documents/stored-credential-transaction-framework-vbs-10-may-17.pdf ""). Types of Credentialed Transactions ---------------------------------- There are several types of credentialed transactions: * **Customer-initiated transaction (CIT):** During a CIT, customers can elect to have their credentials stored for future CITs or for merchant‑initiated transactions (MITs). On `National Payment Gateway`, CITs are also referred to as registering the card. * **Merchant-initiated transaction (MIT):** A MIT is processed without the customer's active involvement and include these transactions: * **Industry practice transaction:** This MIT is performed as a subsequent transaction to a CIT because the initial transaction could not be completed in one transaction. Not every industry practice transaction involves a stored credential. If a stored credential is used only for one transaction, that transaction is not considered a credentialed transaction. * **Standing instruction transactions:** This MIT is performed to follow agreed-upon instructions from the customer for the provision of goods and services. Industry Practice Transactions {#credentials-mit-industry} ========================================================== Industry practice transactions are MITs performed as follow‑on actions to a previous CIT. Although not all of them require stored credentials, repeated use of credentials qualifies them as COF transactions. These industry practice transactions and industry examples are available with your processor: * [Delayed charges](/docs/cybs/en-us/credentials/developer/spg/rest/credentials/credentials-delay-intro/credentials-delay-mit-pan-intro.md ""): Used to add charges after the initial transaction is complete. Examples: hotels (minibar, damages), car rentals (tolls), travel (post-trip charges), and health and wellness add-ons. * [Reauthorizations](/docs/cybs/en-us/credentials/developer/spg/rest/credentials/credentials-reauth-intro/credentials-mit-reauth-intro.md ""): Used when an authorization expires before fulfillment. Examples: long hotel stays, extended rental agreements, multi-week equipment rentals, and delayed subscription boxes. * [Resubmissions](/docs/cybs/en-us/credentials/developer/spg/rest/credentials/credentials-resub-intro/credentials-mit-resub-intro.md ""): Used when a previous authorization attempt fails. Examples: utility auto-pay retries, telecom billing, insurance premiums, and online membership renewals. * [No-shows](/docs/cybs/en-us/credentials/developer/spg/rest/credentials/credentials-noshow-intro/credentials-mit-noshow-intro.md ""): Used when a customer fails to appear for a reserved service for these industries: hotels, rentals, healthcare missed appointments, and restaurant reservation deposits. `Business Center` Transactions ------------------------------ You can create an industry practice transaction in the `Business Center` by requesting a new authorization. Go to the Transaction Management section and confirm that the new authorization is a MIT. Choose one of these reasons for the authorization, which are not applicable for all processors: * Account Top Up * Delayed Charges * No Show * Reauthorization * Resubmission This process requires you to have already stored the customer's credentials from a previous customer-initiated transaction. For more information on storing a customer's credentials in the `Business Center`, see [Customer-Initiated Transactions with Credentials on File](/docs/cybs/en-us/credentials/developer/spg/rest/credentials/credentials-cit-intro.md ""). To create an incremental transaction in the `Business Center`, choose one of these options: * Account Top Up * No Show Standing Instruction Transactions {#credentials-intro-stdinst} ============================================================== Standing instruction transactions are MITs that rely on stored credentials and follow agreed‑upon customer instructions for scheduled or ongoing payments. These transactions must comply with the stored credentials framework, which ensures secure storage and use of customer payment data. All standing instruction transactions begin with a CIT, when customers elect to store their credentials. On `National Payment Gateway` the first payment is authenticated using `3-D Secure`, so that the liability for that transaction rests with the card issuer. For the follow‑up merchant‑initiated charges, liability shifts to your acquirer. These standing instruction transactions and industry examples are available with your processor: * [Installments](/docs/cybs/en-us/credentials/developer/spg/rest/credentials/credentials-install-intro.md ""): A fixed purchase that is split into multiple scheduled payments for these industries: * Retail and electronics: installment plans for device purchases * Furniture and home goods: multi‑month payment plans * Education: tuition installment schedules * Healthcare financing: payment plans for procedures * [Recurring](/docs/cybs/en-us/credentials/developer/spg/rest/credentials/credentials-recur-intro.md ""): Repeated charges for ongoing services for these industries: * Streaming services: video, music, gaming subscriptions * Fitness and wellness: gym memberships, coaching subscriptions * Insurance: monthly premiums * Software and SaaS: business application licenses * [Unscheduled COF](/docs/cybs/en-us/credentials/developer/spg/rest/credentials/credentials-ucof-intro.md ""): Occasional, non‑scheduled charges that are made under a customer authorization for these industries: * Rideshare and transportation: cleaning fees, damage fees * Home services: irregular invoice-based jobs, such as repairs * Professional services: unplanned billable hours or fees * E‑commerce: back-order fulfillment outside a schedule Requirements for Standing Instruction Transactions {#credentials-reqs} ====================================================================== Merchants who offer stored credentials must: * Disclose to cardholders how their credentials will be used. * Obtain the customer's consent to store their credentials. * Notify customers when the terms of use change. * Inform the card issuer during an authorization that the credentials are stored on file. * Identify all transactions that use stored credentials. {#credentials-reqs_ul_j2t_dqy_3tb} Recurring Billing for Recurring Payments {#credentials-mit-recur-rb} ==================================================================== If you are using the Recurring Billing service, do not use this document. `Cybersource` saves and stores payment credentials for recurring transactions, ensuring compliance with COF best practices. For more information on Recurring Billing, see *[Recurring Billing](https://developer.cybersource.com/docs/cybs/en-us/recurring-billing/developer/all/rest/recurring-billing-developer/recur-bill-services-intro.md "")*. `National Payment Gateway` Transactions and Card Types {#credentials-intro-matrix-spg} ====================================================================================== These are the stored credential transaction and card types available on `National Payment Gateway`: | Transaction Type | mada | Mastercard | Visa | |:-------------------------------|:----:|:----------:|:----:| | Initial CIT to register a card | Yes | Yes | Yes | | Subsequent CIT with a PAN | Yes | Yes | Yes | | Installment CIT with a PAN | NA | Yes | Yes | | Installment MIT | NA | Yes | Yes | | Recurring Initial CIT | Yes | Yes | Yes | | Recurring Subsequent MIT | Yes | Yes | Yes | | Unscheduled CIT | Yes | Yes | Yes | | Unscheduled MIT | Yes | Yes | Yes | | Delayed Charges | NA | Yes | Yes | | No Show MIT | NA | Yes | Yes | | Reauthorization | NA | Yes | Yes | | Resubmission | NA | Yes | Yes | | TMS subsequent CIT | Yes | Yes | Yes | | TMS subsequent MIT | Yes | Yes | Yes | | TMS token creation CIT | Yes | Yes | Yes | [Transactions and Card Types] Customer-Initiated Transactions with Credentials on File {#credentials-cit-intro} ================================================================================= A customer-initiated transaction (CIT) is a transaction initiated by the customer. There are two types of CITs: * Customer transactions during which the credentials are stored for future **customer**-initiated transactions. * Customer transactions during which the credentials are stored for future **merchant**-initiated transactions. Customers can initiate a CIT at a merchant payment terminal, through an online purchase transaction, or by making a purchase using a previously stored credential. When storing cardholder data for a CIT, you must also include 3-D Secure authentication credentials to ensure that the CIT can successfully process. Authentication credentials can be stored for future use with the card credentials by doing a non-payment authentication (NPA). `Business Center` ----------------- You can create a new customer-initiated transaction in the `Business Center` by going to the One-Time Payments section and requesting a new authorization. When you have entered the customer's information, you can store the customer's credentials with the customer's permission in the Payment Information section. By doing so, you can perform merchant-initiated transactions for payments that the customer has pre-approved. Storing Customer Credentials with a CIT and PAN {#credentials-cit-storing-intro} ================================================================================ Before you can perform a merchant-initiated transaction (MIT) or a customer-initiated transaction (CIT) with credentials-on-file (COF), you must store the customer's credentials for later use. Further, before you can store the user's credentials, you must get the customer's consent to store their private information. This is also known as establishing a relationship with the customer. Processor-Specific Information ------------------------------ `National Payment Gateway` requires payer authentication data in customer-initiated transactions. When the domestic scheme directory server for mada cards is not available and authentication falls back to the global scheme directory server, the authentication brand response field indicates which directory server was used during the authentication process. Endpoint -------- **Production:** `POST ``https://api.sa.cybersource.com``/pts/v2/payments` **Test:** `POST ``https://apitest.sa.cybersource.com``/pts/v2/payments` Required Fields for Storing Customer Credentials During a CIT {#credentials-cit-storing-required} ================================================================================================= [clientReferenceInformation.code](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md "") : [consumerAuthenticationInformation.acsReferenceNumber](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-acs-reference-num.md "") : [consumerAuthenticationInformation.acsTransactionId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-acs-transaction-id.md "") : [consumerAuthenticationInformation.authenticationDate](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-authentication-date.md "") : [consumerAuthenticationInformation.cavv](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-cavv-a.md "") : [consumerAuthenticationInformation.directoryServerTransactionId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-directory-server-transaction-id.md "") : [consumerAuthenticationInformation.dsReferenceNumber](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-ds-reference-num.md "") : [consumerAuthenticationInformation.paresStatus](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-pares-status-a.md "") : [consumerAuthenticationInformation.paSpecificationVersion](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-pa-specification-version.md "") : [merchantInformation.merchantDescriptor.locality](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-locality.md "") : [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : [orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : [paymentInformation.card.expirationMonth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-mo.md "") : [paymentInformation.card.expirationYear](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-year.md "") : [paymentInformation.card.number](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-number.md "") : [paymentInformation.card.securityCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-security-code-a.md "") : [paymentInformation.card.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-type-a.md "") : [processingInformation.authorizationOptions.initiator.credentialStoredOnFile](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-cof.md "") : [processingInformation.capture](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-capture-a.md "") : [processingInformation.commerceIndicator](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-commerce-ind.md "") : REST Example: Storing Customer Credentials During a mada Card CIT Payment with `3-D Secure` {#credentials-cit-storing-ex-rest-spg} ================================================================================================================================== Request This example includes optional fields. ```keyword { "clientReferenceInformation": { "code": "SPG_REQ_02" }, "consumerAuthenticationInformation": { "cavv": "EHuWW9PiBkWvqE5juRwDzAUFBAk=", "dsReferenceNumber": "dsReferenceNumber-3DS-mada123", "paresStatus": "Y", "acsReferenceNumber": "3DS_LOA_ACS_201_13579", "paSpecificationVersion": "2", "authenticationDate": "20230413121212", "directoryServerTransactionId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b", "acsTransactionId": "f25084f0-5b16-4c0a-ae5d-b248083334b2" }, "processingInformation": { "commerceIndicator": "mada", "authorizationOptions": { "initiator": { "credentialStoredOnFile": true } }, "capture": true }, "orderInformation": { "billTo": { "firstName": "Abdullah", "lastName": "Muhammad", "phoneNumber": "01-4844094", "address2": "P.O.Box: 16335", "address1": "Al Dariyah Dist.", "postalCode": "22028", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100", "currency": "SAR" } }, "merchantInformation": { "categoryCode": 5411, "merchantDescriptor": { "country": "SA", "address1": "API Address", "postalCode": "12987-7318", "locality": "Riyadh", "name": "API Merchant-Name1" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "CARD_NUMBER", "securityCode": "123", "expirationMonth": "12", "type": "060" } } } ``` Response to a Successful Request ``` { "paymentInformation": { "bin": "968208", "issuer": "Al Bank Al Saudi Al Fransi", "binCountry": "SA", "cardBrand": "MADA", "cardType": "PREPAID" }, "paymentAccountInformation": { "card": { "currency": "SAR", "type": "060" } }, "orderInformation": { "amountDetails": { "currency": "SAR", "authorizedAmount": "100.00" } }, "processorInformation": { "approvalCode": "830SPG", "retrievalReferenceNumber": "334210123456", "cardVerification": { "resultCode": "M", "resultCodeRaw": "M" }, "responseCode": "00", "consumerAuthenticationResponse": { "code": "2", "codeRaw": "2" }, "settlementDate": "220915" }, "_links": { "self": { "method": "GET", "href": "/pts/v2/payments/7020303222541234567890" }, "refund": { "method": "POST", "href": "/pts/v2/payments/7020303222541234567890/refunds" } }, "clientReferenceInformation": { "code": "TC_SPG_BASIC-1" }, "consumerAuthenticationInformation": { "token": "abc" }, "reconciliationId": "7020303222541234567890", "status": "COMPLETED", "id": "7020303222541234567890", "submitTimeUtc": "2023-12-08T10:12:02Z" } ``` Storing Customer Credentials with a CIT and `TMS` {#credentials-cit-initial-tms-intro} ====================================================================================== Before you can perform a merchant-initiated transaction (MIT) or a customer-initiated transaction (CIT) with credentials-on-file (COF), you must get the customer's consent to store their payment credentials. This is also known as establishing a relationship with the customer. After you have their consent, you can store their payment credentials for later use. Creating a `TMS` Token ---------------------- When sending the initial CIT, you can create a `TMS` token to store the customer's credentials for the subsequent MITs. To create a `TMS` token, include the processingInformation.actionTokenTypes field in the authorization request. Set the field to one of these values based on the `TMS` token type you want to create: **Customer** : Customer tokens store one or more customer payment instrument tokens and shipping address tokens. : Including a customer token in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "customer" ] ``` : For more information about this `TMS` token type, see [Customer Tokens](https://developer.cybersource.com/docs/cybs/en-us/tms/developer/ctv/rest/tms/tms-overview/tms-token-types/tms-cust-tkn.md "") in the *`Token Management Service` Developer Guide*. **Payment Instrument** : Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token. Including a payment instrument in subsequent MITs eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "paymentInstrument" ] ``` : For more information about this `TMS` token type, see [Payment Instrument Token](https://developer.cybersource.com/docs/cybs/en-us/tms/developer/ctv/rest/tms/tms-overview/tms-token-types/tms-pi-tkn.md "") in the *`Token Management Service` Developer Guide*. **Instrument Identifier** : Instrument identifier tokens store a PAN. Including an instrument identifier in subsequent MITs eliminates the need to include a PAN and the previous transaction's ID. : ``` "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier" ] ``` : For more information about this TMS token type, see [Instrument Identifier Token](https://developer.cybersource.com/docs/cybs/en-us/tms/developer/ctv/rest/tms/tms-overview/tms-token-types/tms-ii-tkn.md "") in the *`Token Management Service` Developer Guide*. **Instrument Identifier, Payment Instrument, and Customer Identifier** : You can also create multiple `TMS` token types in the same authorization. This example includes an instrument identifier, a payment instrument, and a customer token in the same authorization: : ``` "processingInformation": { "actionTokenTypes": [ "instrumentIdentifier", "paymentInstrument", "customer" ] ``` Processor-Specific Information ------------------------------ `National Payment Gateway` requires payer authentication data in customer-initiated transactions. When the domestic scheme directory server for mada cards is not available and authentication falls back to the global scheme directory server, the authentication brand response field indicates which directory server was used during the authentication process. Endpoint -------- **Production:** `POST ``https://api.sa.cybersource.com``/pts/v2/payments` **Test:** `POST ``https://apitest.sa.cybersource.com``/pts/v2/payments` Required Fields for Storing Customer Credentials with a CIT and `TMS` {#credentials-cit-initial-tms-req-fields} =============================================================================================================== [clientReferenceInformation.code](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md "") : [consumerAuthenticationInformation.acsReferenceNumber](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-acs-reference-num.md "") : [consumerAuthenticationInformation.acsTransactionId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-acs-transaction-id.md "") : [consumerAuthenticationInformation.authenticationDate](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-authentication-date.md "") : [consumerAuthenticationInformation.cavv](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-cavv-a.md "") : [consumerAuthenticationInformation.directoryServerTransactionId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-directory-server-transaction-id.md "") : [consumerAuthenticationInformation.dsReferenceNumber](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-ds-reference-num.md "") : [consumerAuthenticationInformation.paresStatus](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-pares-status-a.md "") : [consumerAuthenticationInformation.paSpecificationVersion](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-pa-specification-version.md "") : [merchantInformation.merchantDescriptor.locality](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-locality.md "") : [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : Set the value to `SAR`. [orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : [paymentInformation.card.expirationMonth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-mo.md "") : [paymentInformation.card.expirationYear](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-year.md "") : [paymentInformation.card.number](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-number.md "") : [paymentInformation.card.securityCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-security-code-a.md "") : [paymentInformation.card.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-type-a.md "") : [processingInformation.actionList](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-action-list.md "") : [processingInformation.actionTokenTypes](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-action-token-types.md "") : processingInformation.authorizationOptions.i.initiator. merchantInitiatedTransaction.agreementId : [processingInformation.capture](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-capture-a.md "") : [recurringPaymentInformation.amountType](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/recurring-payment-info-aa/recurring-payment-info-amount-type.md "") : [recurringPaymentInformation.numberOfPayments](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/recurring-payment-info-aa/recurring-payment-info-number-of-payments.md "") : [recurringPaymentInformation.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/recurring-payment-info-aa/recurring-payment-info-type.md "") : REST Example: Storing Customer Credentials with a mada Card CIT and TMS {#credentials-cit-initial-tms-ex-rest-spg} ================================================================================================================== Request This example includes optional fields. ``` { "clientReferenceInformation": { "code": "SPG_REQ_05" }, "recurringPaymentInformation": { "amountType": "0", "numberOfPayments": 3, "type": "1" }, "consumerAuthenticationInformation": { "cavv": "EHuWW9PiBkWvqE5juRwDzAUFBAk=", "dsReferenceNumber": "dsReferenceNumber-3DS-mada123", "paresStatus": "Y", "acsReferenceNumber": "3DS_LOA_ACS_201_13579", "paSpecificationVersion": "2", "authenticationDate": "20230413121212", "directoryServerTransactionId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b", "acsTransactionId": "f25084f0-5b16-4c0a-ae5d-b248083334b2" }, "processingInformation": { "actionList": [ "TOKEN_CREATE" ], "actionTokenTypes": [ "instrumentIdentifier" ], "authorizationOptions": { "initiator": { "merchantInitiatedTransaction": { "agreementId": "AgreementId123$" } } }, "capture": true }, "orderInformation": { "billTo": { "firstName": "Abdullah", "lastName": "Muhammad", "phoneNumber": "01-4844094", "address2": "P.O.Box: 16335", "address1": "Al Dariyah Dist.", "postalCode": "22028", "email": "test-email" }, "amountDetails": { "totalAmount": "100", "currency": "SAR" } }, "merchantInformation": { "categoryCode": 5411, "merchantDescriptor": { "country": "SA", "address1": "API Address", "postalCode": "12987-7318", "locality": "Riyadh", "name": "API Merchant-Name1" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "CARD_NUMBER", "securityCode": "123", "expirationMonth": "12", "type": "060" } } } ``` Response to a Successful Request ``` { "embeddedActions": { "TOKEN_CREATE": { "status": "SUCCESS" } }, "paymentInformation": { "bin": "968208", "issuer": "Al Bank Al Saudi Al Fransi", "binCountry": "SA", "cardBrand": "MADA", "cardType": "060" }, "paymentAccountInformation": { "card": { "currency": "SAR", "type": "060" } }, "submitTimeUtc": "2025-03-14T07:23:16Z", "orderInformation": { "amountDetails": { "currency": "SAR", "authorizedAmount": "100.00" } }, "processorInformation": { "paymentAccountReferenceNumber": "eEwx4ntjEC8Z3KsRUrwxBUv1lEoRw", "approvalCode": "830SPG", "retrievalReferenceNumber": "507307221963", "cardVerification": { "resultCode": "M", "resultCodeRaw": "M" }, "responseCode": "00", "consumerAuthenticationResponse": { "code": "2", "codeRaw": "2" }, "settlementDate": "220915" }, "_links": { "self": { "method": "GET", "href": "/pts/v2/payments/7419369960413859587223" }, "refund": { "method": "POST", "href": "/pts/v2/payments/7419369960413859587223/refunds" } }, "clientReferenceInformation": { "code": "TC_SPG_FE_MD-6" }, "consumerAuthenticationInformation": { "token": "7419369960413859587223" }, "reconciliationId": "7419369960413859587223", "id": "7419369960413859587223", "status": "COMPLETED", "tokenInformation": { "instrumentIdentifierNew": false, "instrumentIdentifier": { "id": "7010020000025033240", "state": "ACTIVE" } } } ``` Using Stored Customer Credentials During a CIT {#credentials-cit-using-intro} ============================================================================= After customers store their credentials on file, you can retrieve these credentials to use with subsequent transactions when the customer is present. Processor-Specific Information ------------------------------ `National Payment Gateway` requires payer authentication data in customer-initiated transactions. When the domestic scheme directory server for mada cards is not available and authentication falls back to the global scheme directory server, the authentication brand response field indicates which directory server was used during the authentication process. Endpoint -------- **Production:** `POST ``https://api.sa.cybersource.com``/pts/v2/payments` **Test:** `POST ``https://apitest.sa.cybersource.com``/pts/v2/payments` Required Fields for Using Customer Credentials During a CIT {#credentials-cit-using-required} ============================================================================================= [clientReferenceInformation.code](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md "") : [consumerAuthenticationInformation.acsReferenceNumber](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-acs-reference-num.md "") : [consumerAuthenticationInformation.acsTransactionId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-acs-transaction-id.md "") : [consumerAuthenticationInformation.authenticationDate](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-authentication-date.md "") : [consumerAuthenticationInformation.cavv](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-cavv-a.md "") : [consumerAuthenticationInformation.directoryServerTransactionId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-directory-server-transaction-id.md "") : [consumerAuthenticationInformation.dsReferenceNumber](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-ds-reference-num.md "") : [consumerAuthenticationInformation.paSpecificationVersion](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-pa-specification-version.md "") : [consumerAuthenticationInformation.paresStatus](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-pares-status-a.md "") : [merchantInformation.categoryCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-category-code-a.md "") : [merchantInformation.merchantDescriptor.address1](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-address1.md "") : [merchantInformation.merchantDescriptor.country](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-country-a.md "") : [merchantInformation.merchantDescriptor.locality](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-locality.md "") : [merchantInformation.merchantDescriptor.name](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-name.md "") : [merchantInformation.merchantDescriptor.postalCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-postalcode.md "") : [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : Set this value to `SAR`. [orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : [orderInformation.billTo.address1](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-address1.md "") : [orderInformation.billTo.address2](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-address2.md "") : [orderInformation.billTo.email](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-email.md "") : [orderInformation.billTo.firstName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-first-name.md "") : [orderInformation.billTo.lastName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-last-name.md "") : [orderInformation.billTo.phoneNumber](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-phone-num.md "") : [orderInformation.billTo.postalCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-postal-code.md "") : [paymentInformation.card.expirationMonth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-mo.md "") : [paymentInformation.card.expirationYear](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-year.md "") : [paymentInformation.card.securityCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-security-code-a.md "") : [paymentInformation.card.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-type-a.md "") : [paymentInformation.instrumentIdentifier.id](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-instrument-identifier-id.md "") : [processingInformation.authorizationOptions.initiator.storedCredentialUsed](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-sc-used.md "") : [processingInformation.capture](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-capture-a.md "") : [processingInformation.commerceIndicator](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-commerce-ind.md "") : [processingInformation.originalPaymentId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-original-payment-id.md "") : REST Example: Using Customer Credentials During a mada Card CIT and `3-D Secure` {#credentials-cit-using-ex-rest-spg} ===================================================================================================================== Request This example includes optional fields. ```keyword { "clientReferenceInformation": { "code": "SPG_REQ_08" }, "consumerAuthenticationInformation": { "cavv": "EHuWW9PiBkWvqE5juRwDzAUFBAk=", "dsReferenceNumber": "dsReferenceNumber-3DS-mada123", "paresStatus": "Y", "acsReferenceNumber": "3DS_LOA_ACS_201_13579", "paSpecificationVersion": "2", "authenticationDate": "20230413121212", "directoryServerTransactionId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b", "acsTransactionId": "f25084f0-5b16-4c0a-ae5d-b248083334b2" }, "processingInformation": { "commerceIndicator": "mada", "authorizationOptions": { "initiator": { "storedCredentialUsed": true } }, "capture": true, "originalPaymentId": "7429098456261234567890" }, "orderInformation": { "billTo": { "firstName": "Abdullah", "lastName": "Muhammad", "phoneNumber": "01-4844094", "address2": "P.O.Box: 16335", "address1": "Al Dariyah Dist.", "postalCode": "22028", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100", "currency": "SAR" } }, "merchantInformation": { "categoryCode": 5411, "merchantDescriptor": { "country": "SA", "address1": "API Address", "postalCode": "12987-7318", "locality": "Riyadh", "name": "API Merchant-Name1" } }, "paymentInformation": { "instrumentIdentifier": { "id": "7010000000026973240" }, "card": { "expirationYear": "2031", "securityCode": "123", "expirationMonth": "12", "type": "060" } } } ``` Response to a Successful Request ``` { "paymentInformation": { "bin": "968208", "issuer": "Al Bank Al Saudi Al Fransi", "binCountry": "SA", "cardBrand": "MADA", "cardType": "060", "instrumentIdentifier": { "id": "7010020000025033240", "state": "ACTIVE" } }, "paymentAccountInformation": { "card": { "currency": "SAR", "type": "060" } }, "submitTimeUtc": "2025-03-14T07:23:40Z", "orderInformation": { "amountDetails": { "currency": "SAR", "authorizedAmount": "100.00" } }, "processorInformation": { "paymentAccountReferenceNumber": "Xnaq8RrWXaCgPOrFAeaZiqLqO0bh2", "approvalCode": "830SPG", "retrievalReferenceNumber": "507307221975", "cardVerification": { "resultCode": "M", "resultCodeRaw": "M" }, "responseCode": "00", "consumerAuthenticationResponse": { "code": "2", "codeRaw": "2" }, "settlementDate": "220915" }, "_links": { "self": { "method": "GET", "href": "/pts/v2/payments/7419370205653628689958" }, "refund": { "method": "POST", "href": "/pts/v2/payments/7419370205653628689958/refunds" } }, "clientReferenceInformation": { "code": "TC_SPG_FE_MD-11" }, "consumerAuthenticationInformation": { "token": "7419370205653628689958" }, "reconciliationId": "7419370205653628689958", "id": "7419370205653628689958", "status": "COMPLETED", "tokenInformation": { "instrumentIdentifierNew": false, "instrumentIdentifier": { "id": "7010020000025033240", "state": "ACTIVE" } }, "embeddedActions": { "TOKEN_RETRIEVE": { "status": "SUCCESS" } } } ``` Delayed Transaction {#credentials-delay-intro} ============================================== Delayed charge transaction is performed to process a supplemental account charge after original services have been rendered and respective payment has been processed. This section describes how to process a merchant-initiated delayed transaction, also known as a delayed charge, using these payment types: * [Merchant-Initiated Delayed Transaction with PAN](/docs/cybs/en-us/credentials/developer/spg/rest/credentials/credentials-delay-intro/credentials-delay-mit-pan-intro.md "") Merchant-Initiated Delayed Transaction with PAN {#credentials-delay-mit-pan-intro} ================================================================================== Delayed charge transaction is performed to process a supplemental account charge after original services have been rendered and respective payment has been processed. Endpoint -------- **Production:** `POST ``https://api.sa.cybersource.com``/pts/v2/payments` **Test:** `POST ``https://apitest.sa.cybersource.com``/pts/v2/payments` Required Fields for a Merchant-Initiated Delayed Transaction {#credentials-delay-mit-pan-req-fields} ==================================================================================================== [clientReferenceInformation.code](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md "") : [merchantInformation.merchantDescriptor.locality](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-locality.md "") : [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : Set the value to `SAR`. [orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : [paymentInformation.card.expirationMonth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-mo.md "") : [paymentInformation.card.expirationYear](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-year.md "") : [paymentInformation.card.number](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-number.md "") : [paymentInformation.card.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-type-a.md "") : processingInformation.authorizationOptions.initiator.merchantInitiatedTransaction.reason : Set the value to `2`. processingInformation.authorizationOptions.initiator.storedCredentialUsed : Set the value to `true`. [processingInformation.authorizationOptions.initiator.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-type.md "") : Set the value to `merchant`. [processingInformation.originalPaymentId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-original-payment-id.md "") : REST Example: Merchant-Initiated Delayed Authorization {#credentials-delay-mit-pan-ex-rest-spg} =============================================================================================== Request This example includes optional fields. ```keyword { "clientReferenceInformation" : { "code" : "TC_SPG_FE_MC-2" }, "processingInformation" : { "authorizationOptions" : { "initiator" : { "type" : "merchant", "merchantInitiatedTransaction" : { "reason":"2" }, "storedCredentialUsed" : true } }, "originalPaymentId" : "7648576824101234567890", "industryDataType" : "restaurant" }, "orderInformation" : { "billTo" : { "firstName" : "Abdullah", "lastName" : "Muhammad", "phoneNumber" : "01-4844094", "address2" : "(PO)Box 16335", "address1" : "Al Dariyah Dist", "postalCode" : "22028", "email" : "test@cybs.com" }, "amountDetails" : { "totalAmount" : "407.01", "currency" : "SAR" } }, "merchantInformation" : { "categoryCode" : 4999, "merchantDescriptor" : { "country" : "SA", "address1" : "Kharj Road", "postalCode" : "12211", "locality" : "Riyadh", "name" : "Al Madina" } }, "paymentInformation" : { "card" : { "expirationYear" : "2026", "number" : "CARD_NUMBER", "expirationMonth" : "12", "type" : "002" } } } ``` Response to a Successful Request ``` { "paymentInformation": { "bin": "411111", "issuer": "CONOTOXIA SP. Z O.O", "binCountry": "PL", "accountType": "Visa Classic", "cardBrand": "VISA", "cardType": "001" }, "submitTimeUtc": "2025-12-04T14:15:01Z", "processorInformation": { "paymentAccountReferenceNumber": "xseGf5M4hG52ucScqGbeYYuS0QTOb", "approvalCode": "830SPG", "transactionId": "kWwN7pwczS2aXrQ", "merchantAdvice": { "code": "01", "codeRaw": "01" }, "consumerAuthenticationResponse": { "code": "2", "codeRaw": "2" }, "cardVerification": { "resultCodeRaw": "N", "resultCode": "N" }, "settlementDate": "220915", "avs": { "code": "M", "codeRaw": "M" }, "retrievalReferenceNumber": "533802000286", "responseCode": "00" }, "_links": { "self": { "method": "GET", "href": "/pts/v2/payments/7648577009261234567890/captures" }, "refund": { "method": "POST", "href": "/pts/v2/payments/7648577009261234567890/refunds" }, "void": { "method": "POST", "href": "/pts/v2/captures/7648577009261234567890/voids" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "clientReferenceInformation": { "code": "TC_SPG_FE_VI-1" }, "consumerAuthenticationInformation": { "token": "7648577009261234567890" }, "id": "7648577009261234567890", "orderInformation": { "amountDetails": { "currency": "SAR", "authorizedAmount": "20100.00", "totalAmount": "20100.00" } }, "reconciliationId": "7648577009261234567890", "status": "PENDING", "embeddedActions": { "CAPTURE": { "status": "PENDING" } } } ``` Reauthorization Transaction {#credentials-reauth-intro} ======================================================= A reauthorization occurs when the completion or fulfillment of the original order or service extends beyond the authorized amount time limit. There are two common reauthorization scenarios: * Split or delayed shipments by a retailer * Extended car rentals, hotel stays, or cruise line bookings Merchant-Initiated Reauthorization Transaction with PAN {#credentials-mit-reauth-intro} ======================================================================================= A reauthorization occurs when the completion or fulfillment of the original order or service extends beyond the authorized amount time limit. There are two common reauthorization scenarios: * Split or delayed shipments by a retailer * Extended car rentals, hotel stays, or cruise line bookings Endpoint -------- **Production:** `POST ``https://api.sa.cybersource.com``/pts/v2/payments` **Test:** `POST ``https://apitest.sa.cybersource.com``/pts/v2/payments` Required Fields for a Merchant-Initiated Reauthorized Transaction {#credentials-mit-reauth-required} ==================================================================================================== [clientReferenceInformation.code](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md "") : [merchantInformation.categoryCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-category-code-a.md "") : [merchantInformation.merchantDescriptor.address1](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-address1.md "") : [merchantInformation.merchantDescriptor.country](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-country-a.md "") : [merchantInformation.merchantDescriptor.locality](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-locality.md "") : [merchantInformation.merchantDescriptor.name](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-name.md "") : [merchantInformation.merchantDescriptor.postalCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-postalcode.md "") : [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : [orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : [orderInformation.billTo.address1](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-address1.md "") : [orderInformation.billTo.address2](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-address2.md "") : [orderInformation.billTo.email](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-email.md "") : [orderInformation.billTo.firstName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-first-name.md "") : [orderInformation.billTo.lastName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-last-name.md "") : [orderInformation.billTo.phoneNumber](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-phone-num.md "") : [orderInformation.billTo.postalCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-postal-code.md "") : [paymentInformation.card.expirationMonth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-mo.md "") : [paymentInformation.card.expirationYear](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-year.md "") : [paymentInformation.card.number](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-number.md "") : [paymentInformation.card.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-type-a.md "") : [processingInformation.authorizationOptions. initiator.merchantInitiatedTransaction.reason](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-mit-reason.md "") : [processingInformation.authorizationOptions. initiator.storedCredentialUsed](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-sc-used.md "") : [processingInformation.authorizationOptions.initiator.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-type.md "") : [processingInformation.industryDataType](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-industry-data-type.md "") : [processingInformation.originalPaymentId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-original-payment-id.md "") : REST Example: Merchant-Initiated Reauthorized Transaction {#credentials-mit-reauth-ex-rest-spg} =============================================================================================== Request This example includes optional fields. ```keyword { "clientReferenceInformation" : { "code" : "TC_SPG_FE_MC-2" }, "processingInformation" : { "authorizationOptions" : { "initiator" : { "type" : "merchant", "merchantInitiatedTransaction" : { "reason":"3" }, "storedCredentialUsed" : true } }, "originalPaymentId" : "7648576824101234567890", "industryDataType" : "restaurant" }, "orderInformation" : { "billTo" : { "firstName" : "Abdullah", "lastName" : "Muhammad", "phoneNumber" : "01-4844094", "address2" : "(PO)Box 16335", "address1" : "Al Dariyah Dist", "postalCode" : "22028", "email" : "test@cybs.com" }, "amountDetails" : { "totalAmount" : "407.01", "currency" : "SAR" } }, "merchantInformation" : { "categoryCode" : 4999, "merchantDescriptor" : { "country" : "SA", "address1" : "Kharj Road", "postalCode" : "12211", "locality" : "Riyadh", "name" : "Al Madina" } }, "paymentInformation" : { "card" : { "expirationYear" : "2026", "number" : "CARD_NUMBER", "expirationMonth" : "12", "type" : "002" } } } ``` Response to a Successful Request ``` { "paymentInformation": { "bin": "411111", "issuer": "CONOTOXIA SP. Z O.O", "binCountry": "PL", "accountType": "Visa Classic", "cardBrand": "VISA", "cardType": "001" }, "submitTimeUtc": "2025-12-04T14:15:01Z", "processorInformation": { "paymentAccountReferenceNumber": "xseGf5M4hG52ucScqGbeYYuS0QTOb", "approvalCode": "830SPG", "transactionId": "kWwN7pwczS2aXrQ", "merchantAdvice": { "code": "01", "codeRaw": "01" }, "consumerAuthenticationResponse": { "code": "2", "codeRaw": "2" }, "cardVerification": { "resultCodeRaw": "N", "resultCode": "N" }, "settlementDate": "220915", "avs": { "code": "M", "codeRaw": "M" }, "retrievalReferenceNumber": "533802000286", "responseCode": "00" }, "_links": { "self": { "method": "GET", "href": "/pts/v2/payments/7648577009261234567890/captures" }, "refund": { "method": "POST", "href": "/pts/v2/payments/7648577009261234567890/refunds" }, "void": { "method": "POST", "href": "/pts/v2/captures/7648577009261234567890/voids" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "clientReferenceInformation": { "code": "TC_SPG_FE_VI-1" }, "consumerAuthenticationInformation": { "token": "7648577009261234567890" }, "id": "7648577009261234567890", "orderInformation": { "amountDetails": { "currency": "SAR", "authorizedAmount": "20100.00", "totalAmount": "20100.00" } }, "reconciliationId": "7648577009261234567890", "status": "PENDING", "embeddedActions": { "CAPTURE": { "status": "PENDING" } } } ``` Resubmission Transaction {#credentials-resub-intro} =================================================== A resubmission transaction is an authorization that you resubmit to recover an outstanding debt from the customer. A common scenario is when a card was initially declined due to insufficient funds, but the goods or services were already delivered to the customer. You can request the resubmission transaction with a PAN or a TMS token. Merchant-Initiated Resubmission Transaction with PAN {#credentials-mit-resub-intro} =================================================================================== A resubmission transaction is an authorization that you resubmit to recover an outstanding debt from the customer. A common scenario is when a card was initially declined due to insufficient funds, but the goods or services were already delivered to the customer. Endpoint -------- **Production:** `POST ``https://api.sa.cybersource.com``/pts/v2/payments` **Test:** `POST ``https://apitest.sa.cybersource.com``/pts/v2/payments` Required Fields for a Merchant-Initiated Resubmitted Transaction {#credentials-mit-resub-required} ================================================================================================== [clientReferenceInformation.code](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md "") : [merchantInformation.categoryCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-category-code-a.md "") : [merchantInformation.merchantDescriptor.address1](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-address1.md "") : [merchantInformation.merchantDescriptor.country](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-country-a.md "") : [merchantInformation.merchantDescriptor.locality](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-locality.md "") : [merchantInformation.merchantDescriptor.name](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-name.md "") : [merchantInformation.merchantDescriptor.postalCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-postalcode.md "") : [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : [orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : [orderInformation.billTo.address1](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-address1.md "") : [orderInformation.billTo.address2](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-address2.md "") : [orderInformation.billTo.email](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-email.md "") : [orderInformation.billTo.firstName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-first-name.md "") : [orderInformation.billTo.lastName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-last-name.md "") : [orderInformation.billTo.phoneNumber](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-phone-num.md "") : [orderInformation.billTo.postalCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-postal-code.md "") : [paymentInformation.card.expirationMonth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-mo.md "") : [paymentInformation.card.expirationYear](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-year.md "") : [paymentInformation.card.number](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-number.md "") : [paymentInformation.card.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-type-a.md "") : [processingInformation.authorizationOptions. initiator.merchantInitiatedTransaction.reason](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-mit-reason.md "") : [processingInformation.authorizationOptions. initiator.storedCredentialUsed](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-sc-used.md "") : [processingInformation.authorizationOptions. initiator.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-type.md "") : [processingInformation.industryDataType](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-industry-data-type.md "") : [processingInformation.originalPaymentId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-original-payment-id.md "") : REST Example: Merchant-Initiated Resubmission Transaction with PAN {#credentials-mit-resub-ex-rest-spg} ======================================================================================================= Request This example includes optional fields. ``` { "clientReferenceInformation" : { "code" : "TC_SPG_FE_MC-2" }, "processingInformation" : { "authorizationOptions" : { "initiator" : { "type" : "merchant", "merchantInitiatedTransaction" : { "reason":"1" }, "storedCredentialUsed" : true } }, "originalPaymentId" : "7648576824101234567890", "industryDataType" : "restaurant" }, "orderInformation" : { "billTo" : { "firstName" : "Abdullah", "lastName" : "Muhammad", "phoneNumber" : "01-4844094", "address2" : "(PO)Box 16335", "address1" : "Al Dariyah Dist", "postalCode" : "22028", "email" : "test-email" }, "amountDetails" : { "totalAmount" : "407.01", "currency" : "SAR" } }, "merchantInformation" : { "categoryCode" : 4999, "merchantDescriptor" : { "country" : "SA", "address1" : "Kharj Road", "postalCode" : "12211", "locality" : "Riyadh", "name" : "Al Madina" } }, "paymentInformation" : { "card" : { "expirationYear" : "2026", "number" : "CARD_NUMBER", "expirationMonth" : "12", "type" : "002" } } } ``` Response to a Successful Request ``` { "paymentInformation": { "bin": "411111", "issuer": "CONOTOXIA SP. Z O.O", "binCountry": "PL", "accountType": "Visa Classic", "cardBrand": "VISA", "cardType": "001" }, "submitTimeUtc": "2025-12-04T14:15:01Z", "processorInformation": { "paymentAccountReferenceNumber": "xseGf5M4hG52ucScqGbeYYuS0QTOb", "approvalCode": "830SPG", "transactionId": "kWwN7pwczS2aXrQ", "merchantAdvice": { "code": "01", "codeRaw": "01" }, "consumerAuthenticationResponse": { "code": "2", "codeRaw": "2" }, "cardVerification": { "resultCodeRaw": "N", "resultCode": "N" }, "settlementDate": "220915", "avs": { "code": "M", "codeRaw": "M" }, "retrievalReferenceNumber": "533802000286", "responseCode": "00" }, "_links": { "self": { "method": "GET", "href": "/pts/v2/payments/7648577009261234567890/captures" }, "refund": { "method": "POST", "href": "/pts/v2/payments/7648577009261234567890/refunds" }, "void": { "method": "POST", "href": "/pts/v2/captures/7648577009261234567890/voids" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "clientReferenceInformation": { "code": "TC_SPG_FE_VI-1" }, "consumerAuthenticationInformation": { "token": "7648577009261234567890" }, "id": "7648577009261234567890", "orderInformation": { "amountDetails": { "currency": "SAR", "authorizedAmount": "20100.00", "totalAmount": "20100.00" } }, "reconciliationId": "7648577009261234567890", "status": "PENDING", "embeddedActions": { "CAPTURE": { "status": "PENDING" } } } ``` No-Show Transactions {#credentials-noshow-intro} ================================================ A no-show authorization occurs when a merchant charges a customer after the customer makes a reservation, and does not show up to claim the reservation. In this situation, the customer is charged an agreed upon fee for not showing up as expected. Merchant-Initiated No-Show Transaction with PAN {#credentials-mit-noshow-intro} =============================================================================== A no-show authorization occurs when a merchant charges a customer after the customer makes a reservation, and does not show up to claim the reservation. In this situation, the customer is charged an agreed upon fee for not showing up as expected. Endpoint -------- **Production:** `POST ``https://api.sa.cybersource.com``/pts/v2/payments` **Test:** `POST ``https://apitest.sa.cybersource.com``/pts/v2/payments` Required Fields for a Merchant-Initiated No-Show Charges {#credentials-mit-noshow-required} =========================================================================================== [clientReferenceInformation.code](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md "") : [merchantInformation.categoryCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-category-code-a.md "") : [merchantInformation.merchantDescriptor.address1](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-address1.md "") : [merchantInformation.merchantDescriptor.country](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-country-a.md "") : [merchantInformation.merchantDescriptor.locality](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-locality.md "") : [merchantInformation.merchantDescriptor.name](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-name.md "") : [merchantInformation.merchantDescriptor.postalCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-postalcode.md "") : [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : [orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : [orderInformation.billTo.address1](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-address1.md "") : [orderInformation.billTo.address2](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-address2.md "") : [orderInformation.billTo.email](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-email.md "") : [orderInformation.billTo.firstName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-first-name.md "") : [orderInformation.billTo.lastName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-last-name.md "") : [orderInformation.billTo.phoneNumber](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-phone-num.md "") : [orderInformation.billTo.postalCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-postal-code.md "") : [paymentInformation.card.expirationMonth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-mo.md "") : [paymentInformation.card.expirationYear](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-year.md "") : [paymentInformation.card.number](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-number.md "") : [paymentInformation.card.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-type-a.md "") : [processingInformation.authorizationOptions. initiator.merchantInitiatedTransaction. agreementId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-merch-init-tran.md "") : [processingInformation.authorizationOptions. initiator.storedCredentialUsed](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-sc-used.md "") : [processingInformation.authorizationOptions.initiator.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-type.md "") : [processingInformation.capture](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-capture-a.md "") : [processingInformation.originalPaymentId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-original-payment-id.md "") : unscheduledPaymentInformation.type : REST Example: Merchant-Initiated No-Show Transaction with a PAN {#credentials-mit-noshow-ex-rest-spg} ===================================================================================================== Request This example includes optional fields. ```keyword { "clientReferenceInformation" : { "code" : "TC_SPG_FE_MC-2" }, "processingInformation" : { "authorizationOptions" : { "initiator" : { "type" : "merchant", "merchantInitiatedTransaction" : { "reason":"4" }, "storedCredentialUsed" : true } }, "originalPaymentId" : "7648576824101234567890", "industryDataType" : "restaurant" }, "orderInformation" : { "billTo" : { "firstName" : "Abdullah", "lastName" : "Muhammad", "phoneNumber" : "01-4844094", "address2" : "(PO)Box 16335", "address1" : "Al Dariyah Dist", "postalCode" : "22028", "email" : "test@cybs.com" }, "amountDetails" : { "totalAmount" : "407.01", "currency" : "SAR" } }, "merchantInformation" : { "categoryCode" : 4999, "merchantDescriptor" : { "country" : "SA", "address1" : "Kharj Road", "postalCode" : "12211", "locality" : "Riyadh", "name" : "Al Madina" } }, "paymentInformation" : { "card" : { "expirationYear" : "2026", "number" : "CARD_NUMBER", "expirationMonth" : "12", "type" : "002" } } } ``` Response to a Successful Request ``` { "paymentInformation": { "bin": "411111", "issuer": "CONOTOXIA SP. Z O.O", "binCountry": "PL", "accountType": "Visa Classic", "cardBrand": "VISA", "cardType": "001" }, "submitTimeUtc": "2025-12-04T14:15:01Z", "processorInformation": { "paymentAccountReferenceNumber": "xseGf5M4hG52ucScqGbeYYuS0QTOb", "approvalCode": "830SPG", "transactionId": "kWwN7pwczS2aXrQ", "merchantAdvice": { "code": "01", "codeRaw": "01" }, "consumerAuthenticationResponse": { "code": "2", "codeRaw": "2" }, "cardVerification": { "resultCodeRaw": "N", "resultCode": "N" }, "settlementDate": "220915", "avs": { "code": "M", "codeRaw": "M" }, "retrievalReferenceNumber": "533802000286", "responseCode": "00" }, "_links": { "self": { "method": "GET", "href": "/pts/v2/payments/7648577009261234567890/captures" }, "refund": { "method": "POST", "href": "/pts/v2/payments/7648577009261234567890/refunds" }, "void": { "method": "POST", "href": "/pts/v2/captures/7648577009261234567890/voids" } }, "paymentAccountInformation": { "card": { "type": "001" } }, "clientReferenceInformation": { "code": "TC_SPG_FE_VI-1" }, "consumerAuthenticationInformation": { "token": "7648577009261234567890" }, "id": "7648577009261234567890", "orderInformation": { "amountDetails": { "currency": "SAR", "authorizedAmount": "20100.00", "totalAmount": "20100.00" } }, "reconciliationId": "7648577009261234567890", "status": "PENDING", "embeddedActions": { "CAPTURE": { "status": "PENDING" } } } ``` Installment Payments {#credentials-install-intro} ================================================= An installment payment is a single purchase of goods or services billed to a customer in multiple transactions over a period of time agreed to by you and the customer. The agreement enables you to charge a specific amount at specified intervals. Installments Service for Installment Payments {#credentials-install-intro_install-service} ------------------------------------------------------------------------------------------ > IMPORTANT > Do not use this document if you are using the Installments service. When using the Installments service, ` Cybersource ` saves and stores payment credentials for installment transactions, ensuring compliance with COF best practices. Customer-Initiated Installment Payments with PAN {#credentials-mit-cit-install-initial-intro} ============================================================================================= An installment payment is a single purchase of goods or services billed to a customer in multiple transactions over a period of time agreed to by you and the customer, and sometimes, the issuing bank. The agreement enables you to charge a specific amount at specified intervals. For customers, installment payments provide greater purchasing power and lower impact on their monthly budget. For you, offering installment payments at checkout can help increase the number of successfully completed purchases. Before you can accept installment payments, you and your acquirer must agree on the maximum number of installments you can accept, which can be different for each card type. > IMPORTANT > Do not use this document if you are using the Installments service. When using the Installments service, ` Cybersource ` saves and stores payment credentials for installment transactions, ensuring compliance with COF best practices. Endpoint -------- **Production:** `POST ``https://api.sa.cybersource.com``/pts/v2/payments` **Test:** `POST ``https://apitest.sa.cybersource.com``/pts/v2/payments` Successful Response ------------------- Store the *network transaction ID* , which is the processorInformation.networkTransactionId field value, from the successful response message. You must include the network transaction ID in subsequent MIT authorization requests in order to associate the CIT to the MIT. Required Fields for Initial Customer-Initiated Installment Payment with a PAN {#credentials-mit-install-initial-reqfields} ========================================================================================================================== [clientReferenceInformation.code](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md "") : [consumerAuthenticationInformation.acsReferenceNumber](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-acs-reference-num.md "") : [consumerAuthenticationInformation.acsTransactionId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-acs-transaction-id.md "") : [consumerAuthenticationInformation.authenticationDate](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-authentication-date.md "") : [consumerAuthenticationInformation.directoryServerTransactionId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-directory-server-transaction-id.md "") : [consumerAuthenticationInformation.paresStatus](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-pares-status-a.md "") : [consumerAuthenticationInformation.specificationVersion](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-specification-version.md "") : [consumerAuthenticationInformation.ucafAuthenticationData](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-ucaf-auth-data.md "") : [consumerAuthenticationInformation.ucafCollectionIndicator](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-ucaf-collect-indicator.md "") : [installmentInformation.amount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/installment-info-aa/installment-info-amount-a.md "") : [installmentInformation.paymentType](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/installment-info-aa/installment-info-payment-type.md "") : [installmentInformation.totalCount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/installment-info-aa/installment-info-total-count.md "") : [merchantInformation.merchantDescriptor.locality](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-locality.md "") : [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : Set the value to `SAR`. [orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : [paymentInformation.card.expirationMonth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-mo.md "") : [paymentInformation.card.expirationYear](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-year.md "") : [paymentInformation.card.number](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-number.md "") : [paymentInformation.card.securityCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-security-code-a.md "") : [paymentInformation.card.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-type-a.md "") : [processingInformation.authorizationOptions.initiator.credentialStoredOnFile](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-cof.md "") : processingInformation.authorizationOptions.i.initiator. merchantInitiatedTransaction.agreementId : [processingInformation.capture](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-capture-a.md "") : [processingInformation.commerceIndicator](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-commerce-ind.md "") : REST Example: Initial Customer-Initiated Installment Payment with a Mastercard PAN and `3-D Secure` {#credentials-cit-install-initial-ex-rest-spg} ================================================================================================================================================== Request This example includes optional fields. ```keyword { "clientReferenceInformation" : { "code" : "TC_SPG_FE_MC-2" }, "consumerAuthenticationInformation" : { "paresStatus" : "Y", "acsReferenceNumber" : "3DS_LOA_ACS_201_13579", "authenticationDate" : "20230413121212", "ucafCollectionIndicator" : "2", "ucafAuthenticationData" : "EHuWW9PiBkWvqE5juRwDzAUFBAk=", "directoryServerTransactionId" : "f25084f05b164c0aae5db24808a95e4b", "specificationVersion" : "2", "acsTransactionId" : "f25084f0-5b16-4c0a-ae5d-b248083334b2" }, "processingInformation" : { "commerceIndicator" : "spa", "authorizationOptions" : { "initiator" : { "credentialStoredOnFile" : true, "merchantInitiatedTransaction" : { "agreementId" : "MIT Agreement-Id_123$" } } }, "capture" : true, "industryDataType" : "auto_rental" }, "aggregatorInformation" : { "subMerchant" : { "id" : "SubMerId123" } }, "orderInformation" : { "billTo" : { "firstName" : "Abdullah", "lastName" : "Muhammad", "phoneNumber" : "01-4844094", "address2" : "(PO)Box 16335", "address1" : "Al Dariyah Dist", "postalCode" : "22028", "email" : "test@cybs.com" }, "amountDetails" : { "totalAmount" : "406.01", "currency" : "SAR" } }, "merchantInformation" : { "categoryCode" : 4999, "merchantDescriptor" : { "country" : "SA", "address1" : "Kharj Road", "postalCode" : "12211", "locality" : "Riyadh", "name" : "Al Madina" } }, "paymentInformation" : { "card" : { "expirationYear" : "2026", "number": "CARD_NUMBER", "securityCode" : "123", "expirationMonth" : "12", "type" : "002" } }, "installmentInformation" : { "amount" : "210", "totalCount" : 3, "paymentType" : "1" } } ``` Response to a Successful Request ``` { "paymentInformation": { "bin": "555555", "issuer": "CONOTOXIA SP. Z O.O", "binCountry": "PL", "accountType": "MASTERCARD", "cardBrand": "MASTERCARD", "cardType": "002" }, "submitTimeUtc": "2025-08-28T11:40:39Z", "processorInformation": { "paymentAccountReferenceNumber": "8atcUKA55teOnsvajmkfaY8Rosg2Z", "approvalCode": "830SPG", "transactionId": "WsPI4kVYXSlXPPK", "merchantAdvice": { "code": "01", "codeRaw": "01" }, "consumerAuthenticationResponse": { "code": "2", "codeRaw": "2" }, "cardVerification": { "resultCodeRaw": "N", "resultCode": "N" }, "settlementDate": "220915", "avs": { "code": "M", "codeRaw": "M" }, "retrievalReferenceNumber": "524011500230", "responseCode": "00" }, "_links": { "self": { "method": "GET", "href": "/pts/v2/payments/7563812390036731704807/captures" }, "refund": { "method": "POST", "href": "/pts/v2/payments/7563812390036731704807/refunds" }, "void": { "method": "POST", "href": "/pts/v2/captures/7563812390036731704807/voids" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "clientReferenceInformation": { "code": "TC_SPG_FE_VI-1" }, "consumerAuthenticationInformation": { "token": "7563812390036731704807", "eciRaw": "05A" }, "id": "7563812390036731704807", "orderInformation": { "amountDetails": { "currency": "SAR", "authorizedAmount": "20100.00", "totalAmount": "20100.00" } }, "reconciliationId": "7563812390036731704807", "status": "PENDING", "embeddedActions": { "CAPTURE": { "status": "PENDING" } } } ``` Merchant-Initiated Installment Payments with PAN {#credentials-mit-install-subsequent-intro} ============================================================================================ After the initial CIT installment payment, subsequent installment payments are merchant-initiated transactions (MITs). Prerequisites ------------- The first transaction in an installment payment is a *customer-initiated transaction* (CIT). Before you can perform a subsequent *merchant-initiated transaction* (MIT), you must store the customer's credentials for later use. Before you can store the user's credentials, you must get the customer's consent to store their private information. This process is also known as establishing a relationship with the customer. Endpoint -------- **Production:** `POST ``https://api.sa.cybersource.com``/pts/v2/payments` **Test:** `POST ``https://apitest.sa.cybersource.com``/pts/v2/payments` Required Fields for a Merchant-Initiated Subsequent Installment Payment {#credentials-mit-install-reqfields} ============================================================================================================ [clientReferenceInformation.code](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md "") : [installmentInformation.amount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/installment-info-aa/installment-info-amount-a.md "") : [installmentInformation.sequence](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/installment-info-aa/installment-info-sequence.md "") : [installmentInformation.totalCount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/installment-info-aa/installment-info-total-count.md "") : [merchantInformation.merchantDescriptor.locality](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-locality.md "") : [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : Set the value to `SAR`. [orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : [paymentInformation.card.expirationMonth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-mo.md "") : [paymentInformation.card.expirationYear](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-year.md "") : [paymentInformation.card.number](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-number.md "") : [paymentInformation.card.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-type-a.md "") : processingInformation.authorizationOptions.i.initiator. merchantInitiatedTransaction.agreementId : [processingInformation.authorizationOptions.initiator.storedCredentialUsed](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-sc-used.md "") : [processingInformation.authorizationOptions.initiator.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-type.md "") : [processingInformation.capture](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-capture-a.md "") : [processingInformation.commerceIndicator](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-commerce-ind.md "") : [processingInformation.originalPaymentId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-original-payment-id.md "") : REST Example: Merchant-Initiated Subsequent Installment Payment with a Mastercard PAN and `3-D Secure` {#credentials-mit-install-ex-rest-spg} ============================================================================================================================================= Request This example includes optional fields. ```keyword { "clientReferenceInformation" : { "code" : "TC_SPG_FE_MC-2" }, "processingInformation" : { "commerceIndicator" : "install", "authorizationOptions" : { "initiator" : { "type" : "merchant", "merchantInitiatedTransaction" : { "agreementId" : "MIT Agreement-Id_123$" }, "storedCredentialUsed" : true } }, "originalPaymentId" : "7491996807960170045280", "capture" : true, "industryDataType" : "restaurant" }, "aggregatorInformation" : { "subMerchant" : { "id" : "SubMerId123" } }, "orderInformation" : { "billTo" : { "firstName" : "Abdullah", "lastName" : "Muhammad", "phoneNumber" : "01-4844094", "address2" : "(PO)Box 16335", "address1" : "Al Dariyah Dist", "postalCode" : "22028", "email" : "test@cybs.com" }, "amountDetails" : { "totalAmount" : "407.01", "currency" : "SAR" } }, "merchantInformation" : { "categoryCode" : 4999, "merchantDescriptor" : { "country" : "SA", "address1" : "Kharj Road", "postalCode" : "12211", "locality" : "Riyadh", "name" : "Al Madina" } }, "paymentInformation" : { "card" : { "expirationYear" : "2026", "number": "CARD_NUMBER", "expirationMonth" : "12", "type" : "002" } }, "installmentInformation" : { "sequence" : 2, "amount" : "210", "totalCount" : 3 } } ``` Response to a Successful Request ``` { "paymentInformation": { "bin": "555555", "issuer": "CONOTOXIA SP. Z O.O", "binCountry": "PL", "accountType": "MASTERCARD Classic", "cardBrand": "MASTERCARD", "cardType": "002" }, "submitTimeUtc": "2025-08-28T11:40:39Z", "processorInformation": { "paymentAccountReferenceNumber": "8atcUKA55teOnsvajmkfaY8Rosg2Z", "approvalCode": "830SPG", "transactionId": "WsPI4kVYXSlXPPK", "merchantAdvice": { "code": "01", "codeRaw": "01" }, "consumerAuthenticationResponse": { "code": "2", "codeRaw": "2" }, "cardVerification": { "resultCodeRaw": "N", "resultCode": "N" }, "settlementDate": "220915", "avs": { "code": "M", "codeRaw": "M" }, "retrievalReferenceNumber": "524011500230", "responseCode": "00" }, "_links": { "self": { "method": "GET", "href": "/pts/v2/payments/7563812390036731704807/captures" }, "refund": { "method": "POST", "href": "/pts/v2/payments/7563812390036731704807/refunds" }, "void": { "method": "POST", "href": "/pts/v2/captures/7563812390036731704807/voids" } }, "paymentAccountInformation": { "card": { "type": "002" } }, "clientReferenceInformation": { "code": "TC_SPG_FE_VI-1" }, "consumerAuthenticationInformation": { "token": "7563812390036731704807", "eciRaw": "05A" }, "id": "7563812390036731704807", "orderInformation": { "amountDetails": { "currency": "SAR", "authorizedAmount": "20100.00", "totalAmount": "20100.00" } }, "reconciliationId": "7563812390036731704807", "status": "PENDING", "embeddedActions": { "CAPTURE": { "status": "PENDING" } } } ``` Recurring Payments {#credentials-recur-intro} ============================================= A recurring payment is a credentials-on-file (COF) transaction in a series of payments that you bill to a customer for a fixed amount at regular intervals that do not exceed one year between transactions. The series of recurring payments is the result of an agreement between you and the customer for the purchase of goods or services that are provided at regular intervals. Recurring payments are also known as *subscriptions*. Recurring Billing Service for Recurring Payments ------------------------------------------------ > IMPORTANT > Do not use this document for the Recurring Billing service. > Use the [Recurring Billing Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/recurring-billing/developer/all/rest/recurring-billing/recur-bill-dev-intro.md ""). When you use the Recurring Billing service, ` Cybersource ` saves and stores payment credentials for recurring transactions, ensuring compliance with COF best practices. Customer-Initiated Recurring Payment with PAN {#credentials-recur-cit-pan-intro} ================================================================================ A recurring payment is a credentials-on-file (COF) transaction in a series of payments that you bill to a customer at a fixed amount, at regular intervals that do not exceed one year between transactions. The series of recurring payments is the result of an agreement between you and the customer for the purchase of goods or services that are provided at regular intervals. Recurring Billing Service for Recurring Payments ------------------------------------------------ > IMPORTANT > Do not use this document for the Recurring Billing service. > Use the [Recurring Billing Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/recurring-billing/developer/all/rest/recurring-billing/recur-bill-dev-intro.md ""). When you use the Recurring Billing service, ` Cybersource ` saves and stores payment credentials for recurring transactions, ensuring compliance with COF best practices. Processor-Specific Information ------------------------------ `National Payment Gateway` requires payer authentication data in customer-initiated transactions. When the domestic scheme directory server for mada cards is not available and authentication falls back to the global scheme directory server, the authentication brand response field indicates which directory server was used during the authentication process. Endpoint -------- **Production:** `POST ``https://api.sa.cybersource.com``/pts/v2/payments` **Test:** `POST ``https://apitest.sa.cybersource.com``/pts/v2/payments` Successful Response ------------------- Store the *network transaction ID* , which is the processorInformation.networkTransactionId field value, from the successful response message. You must include the network transaction ID in subsequent MIT authorization requests in order to associate the CIT to the MIT. Required Fields for a Customer-Initiated Recurring Payment with PAN {#credentials-recur-cit-pan-reqfields} ========================================================================================================== [clientReferenceInformation.code](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md "") : [consumerAuthenticationInformation.acsReferenceNumber](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-acs-reference-num.md "") : [consumerAuthenticationInformation.acsTransactionId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-acs-transaction-id.md "") : [consumerAuthenticationInformation.authenticationDate](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-authentication-date.md "") : [consumerAuthenticationInformation.cavv](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-cavv-a.md "") : [consumerAuthenticationInformation.directoryServerTransactionId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-directory-server-transaction-id.md "") : [consumerAuthenticationInformation.dsReferenceNumber](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-ds-reference-num.md "") : [consumerAuthenticationInformation.paSpecificationVersion](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-pa-specification-version.md "") : [consumerAuthenticationInformation.paresStatus](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-pares-status-a.md "") : [merchantInformation.merchantDescriptor.locality](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-locality.md "") : [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : Set the value to `SAR`. [orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : [paymentInformation.card.expirationMonth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-mo.md "") : [paymentInformation.card.expirationYear](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-year.md "") : [paymentInformation.card.number](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-number.md "") : [paymentInformation.card.securityCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-security-code-a.md "") : [paymentInformation.card.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-type-a.md "") : [processingInformation.authorizationOptions.initiator. credentialStoredOnFile](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-cof.md "") : processingInformation.authorizationOptions.initiator. merchantInitiatedTransaction.agreementId : [processingInformation.capture](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-capture-a.md "") : [processingInformation.commerceIndicator](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-commerce-ind.md "") : [recurringPaymentInformation.amountType](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/recurring-payment-info-aa/recurring-payment-info-amount-type.md "") : [recurringPaymentInformation.numberOfPayments](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/recurring-payment-info-aa/recurring-payment-info-number-of-payments.md "") : [recurringPaymentInformation.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/recurring-payment-info-aa/recurring-payment-info-type.md "") : REST Example: Customer-Initiated Recurring Payment with a mada Card PAN and `3-D Secure` {#credentials-recur-cit-pan-ex-rest-spg} ================================================================================================================================= Request This example includes optional fields. ```keyword { "clientReferenceInformation": { "code": "SPG_REQ_05" }, "recurringPaymentInformation": { "amountType": "0", "numberOfPayments": 3, "type": "1" }, "consumerAuthenticationInformation": { "cavv": "EHuWW9PiBkWvqE5juRwDzAUFBAk=", "dsReferenceNumber": "dsReferenceNumber-3DS-mada123", "paresStatus": "Y", "acsReferenceNumber": "3DS_LOA_ACS_201_13579", "paSpecificationVersion": "2", "authenticationDate": "20230413121212", "directoryServerTransactionId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b", "acsTransactionId": "f25084f0-5b16-4c0a-ae5d-b248083334b2" }, "processingInformation": { "commerceIndicator": "mada", "authorizationOptions": { "initiator": { "credentialStoredOnFile":true, "merchantInitiatedTransaction": { "agreementId": "AgreementId123$" } } }, "capture": true }, "orderInformation": { "billTo": { "firstName": "Abdullah", "lastName": "Muhammad", "phoneNumber": "01-4844094", "address2": "P.O.Box: 16335", "address1": "Al Dariyah Dist.", "postalCode": "22028", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100", "currency": "SAR" } }, "merchantInformation": { "categoryCode": 5411, "merchantDescriptor": { "country": "SA", "address1": "API Address", "postalCode": "12987-7318", "locality": "Riyadh", "name": "API Merchant-Name1" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "CARD_NUMBER", "securityCode": "123", "expirationMonth": "12", "type": "060" } } } ``` Response to a Successful Request ``` { "paymentInformation": { "bin": "968208", "issuer": "Al Bank Al Saudi Al Fransi", "binCountry": "SA", "cardBrand": "MADA", "cardType": "PREPAID" }, "paymentAccountInformation": { "card": { "currency": "SAR", "type": "060" } }, "orderInformation": { "amountDetails": { "currency": "SAR", "authorizedAmount": "100.00" } }, "processorInformation": { "approvalCode": "830SPG", "retrievalReferenceNumber": "334210123456", "cardVerification": { "resultCode": "M", "resultCodeRaw": "M" }, "responseCode": "00", "consumerAuthenticationResponse": { "code": "2", "codeRaw": "2" }, "settlementDate": "220915" }, "_links": { "self": { "method": "GET", "href": "/pts/v2/payments/7020303222541234567890" }, "refund": { "method": "POST", "href": "/pts/v2/payments/7020303222541234567890/refunds" } }, "clientReferenceInformation": { "code": "TC_SPG_BASIC-1" }, "consumerAuthenticationInformation": { "token": "abc" }, "reconciliationId": "7020303222541234567890", "status": "COMPLETED", "id": "7020303222541234567890", "submitTimeUtc": "2023-12-08T10:12:02Z" } ``` Merchant-Initiated Recurring Payments with PAN {#credentials-recur-mit-pan-intro} ================================================================================= After the initial recurring payment (CIT), subsequent recurring payments are merchant-initiated transactions (MITs). Prerequisites ------------- The first transaction in a recurring payment is a customer-initiated transaction (CIT). Before you can perform a subsequent merchant-initiated transaction (MIT), you must store the customer's credentials for later use. Before you can store the customer's credentials, you must get their consent to store their private information. This is also known as establishing a relationship with the customer. Endpoint -------- **Production:** `POST ``https://api.sa.cybersource.com``/pts/v2/payments` **Test:** `POST ``https://apitest.sa.cybersource.com``/pts/v2/payments` Required Fields for a Merchant-Initiated Recurring Payment {#credentials-recur-mit-pan-reqfields} ================================================================================================= [clientReferenceInformation.code](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md "") : [merchantInformation.merchantDescriptor.locality](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-locality.md "") : [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : Set the value to `SAR`. [orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : [paymentInformation.card.expirationMonth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-mo.md "") : [paymentInformation.card.expirationYear](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-year.md "") : [paymentInformation.card.number](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-number.md "") : [paymentInformation.card.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-type-a.md "") : processingInformation.authorizationOptions.initiator. merchantInitiatedTransaction.agreementId : [processingInformation.authorizationOptions.initiator. storedCredentialUsed](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-sc-used.md "") : [processingInformation.authorizationOptions.initiator.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-type.md "") : [processingInformation.capture](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-capture-a.md "") : [processingInformation.commerceIndicator](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-commerce-ind.md "") : [processingInformation.originalPaymentId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-original-payment-id.md "") : [recurringPaymentInformation.amountType](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/recurring-payment-info-aa/recurring-payment-info-amount-type.md "") : [recurringPaymentInformation.numberOfPayments](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/recurring-payment-info-aa/recurring-payment-info-number-of-payments.md "") : recurringPaymentInformation.sequenceNumber : REST Example: Merchant-Initiated Recurring Payment with a mada Card PAN and `3-D Secure` {#credentials-recur-mit-pan-ex-rest-spg} ================================================================================================================================= Request This example includes optional fields. ```keyword { "clientReferenceInformation": { "code": "SPG_REQ_11" }, "recurringPaymentInformation": { "amountType": "0", "numberOfPayments": 3, "sequenceNumber": 1 }, "processingInformation": { "commerceIndicator": "recurring", "capture": true, "originalPaymentId": "7429104506861234567890", "authorizationOptions": { "initiator": { "storedCredentialUsed": true, "type": "merchant", "merchantInitiatedTransaction": { "agreementId": "AgreementId123$" } } } }, "orderInformation": { "billTo": { "firstName": "Abdullah", "lastName": "Muhammad", "phoneNumber": "01-4844094", "address2": "P.O.Box: 16335", "address1": "Al Dariyah Dist.", "postalCode": "22028", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100", "currency": "SAR" } }, "merchantInformation": { "categoryCode": 5411, "merchantDescriptor": { "country": "SA", "address1": "API Address", "postalCode": "12987-7318", "locality": "Riyadh", "name": "API Merchant-Name1" } }, "paymentInformation": { "card": { "number": "CARD_NUMBER", "expirationYear": "2031", "expirationMonth": "12", "type": "060" } } } ``` Response to a Successful Request ``` { "paymentInformation": { "bin": "968208", "issuer": "Al Bank Al Saudi Al Fransi", "binCountry": "SA", "cardBrand": "MADA", "cardType": "PREPAID" }, "paymentAccountInformation": { "card": { "currency": "SAR", "type": "060" } }, "orderInformation": { "amountDetails": { "currency": "SAR", "authorizedAmount": "100.00" } }, "processorInformation": { "approvalCode": "830SPG", "retrievalReferenceNumber": "334210123456", "cardVerification": { "resultCode": "M", "resultCodeRaw": "M" }, "responseCode": "00", "consumerAuthenticationResponse": { "code": "2", "codeRaw": "2" }, "settlementDate": "220915" }, "_links": { "self": { "method": "GET", "href": "/pts/v2/payments/7020303222541234567890" }, "refund": { "method": "POST", "href": "/pts/v2/payments/7020303222541234567890/refunds" } }, "clientReferenceInformation": { "code": "TC_SPG_BASIC-1" }, "consumerAuthenticationInformation": { "token": "abc" }, "reconciliationId": "7020303222541234567890", "status": "COMPLETED", "id": "7020303222541234567890", "submitTimeUtc": "2023-12-08T10:12:02Z" } ``` Merchant-Initiated Recurring Payment with `TMS` {#credentials-recur-mit-tms-intro} ================================================================================== After the customer-initiated recurring payment, you can send merchant-initiated recurring payments using one or more `TMS` token types: **Customer** : Customer tokens store one or more customer payment instrument tokens and shipping address tokens. : Including a customer token eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "paymentInformation": { "customer": { "id": "07C9CA98022DA498E063A2598D0AA400" } } ``` : For more information about this `TMS` token type, see [Customer Tokens](https://developer.cybersource.com/docs/cybs/en-us/tms/developer/ctv/rest/tms/tms-overview/tms-token-types/tms-cust-tkn.md "") in the *`Token Management Service` Developer Guide*. **Payment Instrument** : Payment instrument tokens store an instrument identifier token, card information, and billing information. Payment instruments are not linked to a customer token. : Including a payment instrument eliminates the need to include billing information, card information, and the previous transaction's ID. : ``` "paymentInformation": { "paymentInstrument": { "id": "07CA24EF20F9E2C9E063A2598D0A8565" } } ``` : For more information about this `TMS` token type, see [Payment Instrument Token](https://developer.cybersource.com/docs/cybs/en-us/tms/developer/ctv/rest/tms/tms-overview/tms-token-types/tms-pi-tkn.md "") in the *`Token Management Service` Developer Guide*. **Instrument Identifier** : Instrument identifier tokens store only a PAN. Including an instrument identifier eliminates the need to include a PAN and the previous transaction's ID. : ``` "paymentInformation": { "instrumentIdentifier": { "id": "7010000000016241111" } } ``` : For more information about this `TMS` token type, see [Instrument Identifier Token](https://developer.cybersource.com/docs/cybs/en-us/tms/developer/ctv/rest/tms/tms-overview/tms-token-types/tms-ii-tkn.md "") in the *`Token Management Service` Developer Guide*. Prerequisites ------------- The first transaction in a recurring payment is a customer-initiated transaction (CIT). Before you can perform a subsequent merchant-initiated transaction (MIT), you must store the customer's credentials for later use. Before you can store the customer's credentials, you must get their consent to store their private information. This is also known as establishing a relationship with the customer. Endpoint -------- **Production:** `POST ``https://api.sa.cybersource.com``/pts/v2/payments` **Test:** `POST ``https://apitest.sa.cybersource.com``/pts/v2/payments` Required Fields for a Merchant-Initiated Recurring Payment with `TMS` {#credentials-recur-mit-tms-reqfields} ============================================================================================================ [clientReferenceInformation.code](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md "") : [merchantInformation.categoryCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-category-code-a.md "") : [merchantInformation.merchantDescriptor.address1](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-address1.md "") : [merchantInformation.merchantDescriptor.country](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-country-a.md "") : [merchantInformation.merchantDescriptor.locality](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-locality.md "") : [merchantInformation.merchantDescriptor.name](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-name.md "") : [merchantInformation.merchantDescriptor.postalCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-postalcode.md "") : [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : [orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : [orderInformation.billTo.address1](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-address1.md "") : [orderInformation.billTo.address2](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-address2.md "") : [orderInformation.billTo.email](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-email.md "") : [orderInformation.billTo.firstName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-first-name.md "") : [orderInformation.billTo.lastName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-last-name.md "") : [orderInformation.billTo.phoneNumber](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-phone-num.md "") : [orderInformation.billTo.postalCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-postal-code.md "") : [paymentInformation.card.expirationMonth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-mo.md "") : [paymentInformation.card.expirationYear](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-year.md "") : [paymentInformation.card.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-type-a.md "") : [paymentInformation.instrumentIdentifier.id](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-instrument-identifier-id.md "") : processingInformation.authorizationOptions.initiator.merchantInitiatedTransaction.agreementId : [processingInformation.authorizationOptions.initiator.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-type.md "") : [processingInformation.capture](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-capture-a.md "") : [processingInformation.commerceIndicator](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-commerce-ind.md "") : [processingInformation.originalPaymentId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-original-payment-id.md "") : [recurringPaymentInformation.amountType](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/recurring-payment-info-aa/recurring-payment-info-amount-type.md "") : [recurringPaymentInformation.numberOfPayments](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/recurring-payment-info-aa/recurring-payment-info-number-of-payments.md "") : recurringPaymentInformation.sequenceNumber : Instrument Identifier Required Fields ------------------------------------- If you are using the paymentInformation.instrumentIdentifier.id token, include these required fields in addition to the required fields listed above. [orderInformation.billTo.address1](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-address1.md "") : [orderInformation.billTo.administrativeArea](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-admin-area.md "") : [orderInformation.billTo.country](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-company-country.md "") : [orderInformation.billTo.email](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-email.md "") : [orderInformation.billTo.firstName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-first-name.md "") : [orderInformation.billTo.lastName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-last-name.md "") : [orderInformation.billTo.locality](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-locality.md "") : [orderInformation.billTo.phoneNumber](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-phone-num.md "") : [orderInformation.billTo.postalCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-postal-code.md "") : [paymentInformation.card.expirationMonth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-mo.md "") : [paymentInformation.card.expirationYear](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-year.md "") : Card-Specific Field ------------------- Some card companies require additional fields when making authorizations with stored credentials. Include this field if you are using these card types: Discover : processingInformation.authorizationOptions.initiator. merchantInitiatedTransaction.originalAuthorizedAmount Mastercard : Mastercard supports subscription and standing order payments instead of recurring payments. REST Example: Merchant-Initiated Recurring Payment with a `TMS` Instrument Identifier {#credentials-recur-mit-tms-iid-ex-rest-spg} ================================================================================================================================== Request This example includes optional fields. ```keyword { "clientReferenceInformation": { "code": "SPG_REQ_11" }, "recurringPaymentInformation": { "amountType": "0", "numberOfPayments": 3, "sequenceNumber": 1 }, "processingInformation": { "commerceIndicator": "recurring", "capture": true, "originalPaymentId": "7174099314941234567890", "authorizationOptions": { "initiator": { "type": "merchant", "merchantInitiatedTransaction": { "agreementId": "AgreementId123$" } } } }, "orderInformation": { "billTo": { "firstName": "Abdullah", "lastName": "Muhammad", "phoneNumber": "01-4844094", "address2": "P.O.Box: 16335", "address1": "Al Dariyah Dist.", "postalCode": "22028", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100", "currency": "SAR" } }, "merchantInformation": { "categoryCode": 5411, "merchantDescriptor": { "country": "SA", "address1": "API Address", "postalCode": "12987-7318", "locality": "Riyadh", "name": "API Merchant-Name1" } }, "paymentInformation": { "instrumentIdentifier": { "id": "7010000000026973240" }, "card": { "expirationYear": "2031", "expirationMonth": "12", "type": "060" } } } ``` Response to a Successful Request ``` { "paymentInformation": { "bin": "968208", "issuer": "Al Bank Al Saudi Al Fransi", "binCountry": "SA", "cardBrand": "MADA", "cardType": "060", "instrumentIdentifier": { "id": "7010020000025033240", "state": "ACTIVE" } }, "paymentAccountInformation": { "card": { "currency": "SAR", "type": "060" } }, "submitTimeUtc": "2025-03-14T07:23:40Z", "orderInformation": { "amountDetails": { "currency": "SAR", "authorizedAmount": "100.00" } }, "processorInformation": { "paymentAccountReferenceNumber": "Xnaq8RrWXaCgPOrFAeaZiqLqO0bh2", "approvalCode": "830SPG", "retrievalReferenceNumber": "507307221975", "cardVerification": { "resultCode": "M", "resultCodeRaw": "M" }, "responseCode": "00", "consumerAuthenticationResponse": { "code": "2", "codeRaw": "2" }, "settlementDate": "220915" }, "_links": { "self": { "method": "GET", "href": "/pts/v2/payments/7419370205653628689958" }, "refund": { "method": "POST", "href": "/pts/v2/payments/7419370205653628689958/refunds" } }, "clientReferenceInformation": { "code": "TC_SPG_FE_MD-11" }, "consumerAuthenticationInformation": { "token": "7419370205653628689958" }, "reconciliationId": "7419370205653628689958", "id": "7419370205653628689958", "status": "COMPLETED", "tokenInformation": { "instrumentIdentifierNew": false, "instrumentIdentifier": { "id": "7010020000025033240", "state": "ACTIVE" } }, "embeddedActions": { "TOKEN_RETRIEVE": { "status": "SUCCESS" } } } ``` Unscheduled COF Payments {#credentials-ucof-intro} ================================================== An unscheduled credentials-on-file (COF) transaction uses stored payment information for a fixed or variable amount that does not occur regularly. An account top-up is one kind of unscheduled COF. Customer-Initiated Unscheduled COF Payment with PAN {#credentials-cit-ucof-initial-intro} ========================================================================================= An unscheduled credentials-on-file (COF) transaction uses stored payment information for a fixed or variable amount that does not occur regularly. An account top-up is one kind of unscheduled COF. Processor-Specific Information ------------------------------ `National Payment Gateway` requires payer authentication data in customer-initiated transactions. When the domestic scheme directory server for mada cards is not available and authentication falls back to the global scheme directory server, the authentication brand response field indicates which directory server was used during the authentication process. Endpoint -------- **Production:** `POST ``https://api.sa.cybersource.com``/pts/v2/payments` **Test:** `POST ``https://apitest.sa.cybersource.com``/pts/v2/payments` Successful Response ------------------- Store the *network transaction ID* , which is the processorInformation.networkTransactionId field value, from the successful response message. You must include the network transaction ID in subsequent MIT authorization requests in order to associate the CIT to the MIT. Required Fields for a Customer-Initiated Unscheduled COF Payment with PAN {#credentials-cit-ucof-initial-reqfields} =================================================================================================================== [clientReferenceInformation.code](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md "") : [consumerAuthenticationInformation.acsReferenceNumber](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-acs-reference-num.md "") : [consumerAuthenticationInformation.acsTransactionId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-acs-transaction-id.md "") : [consumerAuthenticationInformation.authenticationDate](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-authentication-date.md "") : [consumerAuthenticationInformation.cavv](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-cavv-a.md "") : [consumerAuthenticationInformation.directoryServerTransactionId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-directory-server-transaction-id.md "") : [consumerAuthenticationInformation.dsReferenceNumber](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-ds-reference-num.md "") : [consumerAuthenticationInformation.paSpecificationVersion](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-pa-specification-version.md "") : [consumerAuthenticationInformation.paresStatus](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-pares-status-a.md "") : [merchantInformation.merchantDescriptor.locality](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-locality.md "") : [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : Set the value to `SAR`. [orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : [paymentInformation.card.expirationMonth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-mo.md "") : [paymentInformation.card.expirationYear](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-year.md "") : [paymentInformation.card.number](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-number.md "") : [paymentInformation.card.securityCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-security-code-a.md "") : [paymentInformation.card.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-type-a.md "") : [processingInformation.authorizationOptions.initiator.credentialStoredOnFile](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-cof.md "") : processingInformation.authorizationOptions.i.initiator. merchantInitiatedTransaction.agreementId : [processingInformation.authorizationOptions.initiator.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-type.md "") : [processingInformation.capture](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-capture-a.md "") : [processingInformation.commerceIndicator](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-commerce-ind.md "") : unscheduledPaymentInformation.type : REST Example: Customer-Initiated Unscheduled mada Card COF Payment with PAN and `3-D Secure` {#credentials-cit-ucof-initial-ex-rest-spg} ======================================================================================================================================== Request This example includes optional fields. ```keyword { "clientReferenceInformation": { "code": "SPG_REQ_02" }, "consumerAuthenticationInformation": { "cavv": "EHuWW9PiBkWvqE5juRwDzAUFBAk=", "dsReferenceNumber": "dsReferenceNumber-3DS-mada123", "paresStatus": "Y", "acsReferenceNumber": "3DS_LOA_ACS_201_13579", "paSpecificationVersion": "2", "authenticationDate": "20230413121212", "directoryServerTransactionId": "f25084f0-5b16-4c0a-ae5d-b24808a95e4b", "acsTransactionId": "f25084f0-5b16-4c0a-ae5d-b248083334b2" }, "processingInformation": { "commerceIndicator": "mada", "authorizationOptions": { "initiator": { "type": "customer", "credentialStoredOnFile":true, "merchantInitiatedTransaction": { "agreementId": "AgreementId123$" } } }, "capture": true }, "unscheduledPaymentInformation": { "type": "1" }, "orderInformation": { "billTo": { "firstName": "Abdullah", "lastName": "Muhammad", "phoneNumber": "01-4844094", "address2": "P.O.Box: 16335", "address1": "Al Dariyah Dist.", "postalCode": "22028", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100", "currency": "SAR" } }, "merchantInformation": { "categoryCode": 5411, "merchantDescriptor": { "country": "SA", "address1": "API Address", "postalCode": "12987-7318", "locality": "Riyadh", "name": "API Merchant-Name1" } }, "paymentInformation": { "card": { "expirationYear": "2031", "number": "CARD_NUMBER", "securityCode": "123", "expirationMonth": "12", "type": "060" } } } ``` Response to a Successful Request ``` { "paymentInformation": { "bin": "968208", "issuer": "Al Bank Al Saudi Al Fransi", "binCountry": "SA", "cardBrand": "MADA", "cardType": "PREPAID" }, "paymentAccountInformation": { "card": { "currency": "SAR", "type": "060" } }, "orderInformation": { "amountDetails": { "currency": "SAR", "authorizedAmount": "100.00" } }, "processorInformation": { "approvalCode": "830SPG", "retrievalReferenceNumber": "334210123456", "cardVerification": { "resultCode": "M", "resultCodeRaw": "M" }, "responseCode": "00", "consumerAuthenticationResponse": { "code": "2", "codeRaw": "2" }, "settlementDate": "220915" }, "_links": { "self": { "method": "GET", "href": "/pts/v2/payments/7020303222541234567890" }, "refund": { "method": "POST", "href": "/pts/v2/payments/7020303222541234567890/refunds" } }, "clientReferenceInformation": { "code": "TC_SPG_BASIC-1" }, "consumerAuthenticationInformation": { "token": "abc" }, "reconciliationId": "7020303222541234567890", "status": "COMPLETED", "id": "7020303222541234567890", "submitTimeUtc": "2023-12-08T10:12:02Z" } ``` Merchant-Initiated Unscheduled COF Payment with PAN {#credentials-mit-unsched-subsequent-intro} =============================================================================================== After the initial CIT unscheduled COF payment, subsequent unscheduled COF transactions are merchant-initiated transactions (MITs). Prerequisites ------------- The first transaction in an unscheduled COF payment is a customer-initiated transaction (CIT). Before you can perform a subsequent merchant-initiated transaction (MIT), you must store the customer's credentials for later use. Before you can store the user's credentials, you must get the customer's consent to store their private information. This process is also known as establishing a relationship with the customer. Endpoint -------- **Production:** `POST ``https://api.sa.cybersource.com``/pts/v2/payments` **Test:** `POST ``https://apitest.sa.cybersource.com``/pts/v2/payments` Required Fields for a Subsequent MIT Unscheduled COF Payment {#credentials-mit-unsched-reqfields} ================================================================================================= [clientReferenceInformation.code](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/client-ref-info-aa/client-ref-info-code.md "") : [merchantInformation.merchantDescriptor.locality](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-locality.md "") : [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : Set the value to `SAR`. [orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : [paymentInformation.card.expirationMonth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-mo.md "") : [paymentInformation.card.expirationYear](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-year.md "") : [paymentInformation.card.number](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-number.md "") : [paymentInformation.card.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-type-a.md "") : processingInformation.authorizationOptions.i.initiator. merchantInitiatedTransaction.agreementId : [processingInformation.authorizationOptions.initiator.storedCredentialUsed](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-sc-used.md "") : [processingInformation.authorizationOptions.initiator.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-initiator-type.md "") : [processingInformation.capture](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-capture-a.md "") : [processingInformation.originalPaymentId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-original-payment-id.md "") : unscheduledPaymentInformation.type : REST Example: Merchant-Initiated Unscheduled mada Card COF Payment with PAN and `3-D Secure` {#credentials-mit-unsched-ex-rest-spg} =================================================================================================================================== Request This example includes optional fields. ```keyword { "clientReferenceInformation": { "code": "SPG_REQ_11" }, "processingInformation": { "capture": true, "originalPaymentId": "7429102546561234567890", "authorizationOptions": { "initiator": { "type": "merchant", "storedCredentialUsed": true, "merchantInitiatedTransaction": { "agreementId": "AgreementId123$" } } } }, "unscheduledPaymentInformation": { "type": "2" }, "orderInformation": { "billTo": { "firstName": "Abdullah", "lastName": "Muhammad", "phoneNumber": "01-4844094", "address2": "P.O.Box: 16335", "address1": "Al Dariyah Dist.", "postalCode": "22028", "email": "test@cybs.com" }, "amountDetails": { "totalAmount": "100", "currency": "SAR" } }, "merchantInformation": { "categoryCode": 5411, "merchantDescriptor": { "country": "SA", "address1": "API Address", "postalCode": "12987-7318", "locality": "Riyadh", "name": "API Merchant-Name1" } }, "paymentInformation": { "card": { "number": "CARD_NUMBER", "expirationYear": "2031", "expirationMonth": "12", "type": "060" } } } ``` Response to a Successful Request ``` { "paymentInformation": { "bin": "968208", "issuer": "Al Bank Al Saudi Al Fransi", "binCountry": "SA", "cardBrand": "MADA", "cardType": "PREPAID" }, "paymentAccountInformation": { "card": { "currency": "SAR", "type": "060" } }, "orderInformation": { "amountDetails": { "currency": "SAR", "authorizedAmount": "100.00" } }, "processorInformation": { "approvalCode": "830SPG", "retrievalReferenceNumber": "334210123456", "cardVerification": { "resultCode": "M", "resultCodeRaw": "M" }, "responseCode": "00", "consumerAuthenticationResponse": { "code": "2", "codeRaw": "2" }, "settlementDate": "220915" }, "_links": { "self": { "method": "GET", "href": "/pts/v2/payments/7020303222541234567890" }, "refund": { "method": "POST", "href": "/pts/v2/payments/7020303222541234567890/refunds" } }, "clientReferenceInformation": { "code": "TC_SPG_BASIC-1" }, "consumerAuthenticationInformation": { "token": "abc" }, "reconciliationId": "7020303222541234567890", "status": "COMPLETED", "id": "7020303222541234567890", "submitTimeUtc": "2023-12-08T10:12:02Z" } ``` Mastercard Standing Order Payment {#credentials-mit-stand-order-intro} ====================================================================== A standing order payment is a recurring COF transaction that is a variable amount at a regular interval, such as a utility bill, not to exceed one year between transactions. The series of recurring payments is the result of an agreement between you and the customer for the purchase of goods or services that are provided at regular intervals. Mastercard Subscription Payment {#credentials-mc-subscription-intro} ==================================================================== A subscription payment is a recurring COF transaction that is processed at a fixed amount at regular intervals not to exceed one year between transactions. The series of recurring payments is the result of an agreement between you and the customer for the purchase of goods or services that are provided at regular intervals.