> ## Documentation Index > Fetch the complete documentation index at: https://devzone.nayax.com/llms.txt > Use this file to discover all available pages before exploring further. # Charge Token ## OpenAPI ````yaml openapi/ecom.yaml POST /charge-token openapi: 3.0.1 info: title: Nayax Ecom SDK API version: v1 description: >- This OpenAPI specification describes the Nayax SDK API, designed to facilitate e-commerce transactions, including initialization, payment processing, and card token management. It supports various transaction types such as Customer-Initiated Transactions (CIT), Merchant-Initiated Transactions (MIT), and Card-on-File (COF) operations. The API focuses on secure authentication, efficient transaction flows, and real-time status updates, with robust error handling and logging capabilities. servers: - url: https://api.nayax.com/sdk description: Production Nayax SDK API security: - BearerAuth: [] tags: - name: Payments description: Operations related to the Nayax SDK API for e-commerce transactions. - name: Testing description: Endpoints for testing connectivity. paths: /charge-token: post: tags: - Payments summary: Charge Token requestBody: description: Request to charge a saved token for a payment. required: true content: application/json: schema: $ref: '#/components/schemas/TransactionRequest' examples: chargeTokenRequestMIT: summary: Example Charge Token Request (MIT) value: basicInfo: amount: 25.5 currency: EUR countryCode: DE requestType: 0 entryMode: 1 tokenModel: 1 cvc: null token: NAYAXTOK12345 merchantRequestId: MERCHANT_MIT_001 transactionId: null transactionTimeUtc: null isSaveTokenWithoutConsent: false machineInfo: machineId: '0434334921100366' cardHolderInfo: cardholderEmail: customer@example.com cardHolderUniqId: unique_customer_id_123 additionalInfo: additionalData: '{"loyaltyPoints": 100}' additionalReceiptData: '[{"key":"product", "value":"Premium Service"}]' validationKey: AUTH_VALID_KEY_XYZ chargeTokenRequestCIT: summary: Example Charge Token Request (CIT) value: basicInfo: amount: 10 currency: GBP countryCode: UK requestType: 0 entryMode: 2 tokenModel: 2 cvc: 123 token: NAYAXTOK67890 merchantRequestId: MERCHANT_CIT_002 transactionId: null transactionTimeUtc: null isSaveTokenWithoutConsent: false machineInfo: machineId: '0434334921100367' cardHolderInfo: cardholderEmail: customer2@example.com cardHolderUniqId: unique_customer_id_456 additionalInfo: additionalData: '{"discountCode": "SAVE10"}' additionalReceiptData: '[{"key":"item", "value":"Book A"}]' validationKey: AUTH_VALID_KEY_ABC responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/TransactionResponse' examples: chargeTokenResponseApproved: summary: Example Charge Token Response (Approved) value: status: verdict: Approved code: 0 statusMessage: Payment processed successfully. basicInfo: amount: 25.5 currency: EUR merchantRequestId: MERCHANT_MIT_001 transactionId: NAYAXTRANS98765 transactionTimeUtc: '2025-08-28T10:30:00Z' paymentInfo: amount: 25.5 currency: EUR nayaxTokenId: NAYAXTOK12345 siteId: 1 providerTransactionId: PSP_TRANS_ABC decimalPlace: 2 chargeTokenResponseDeclined: summary: Example Charge Token Response (Declined) value: status: verdict: Declined code: 981 statusMessage: Unauthorized – Machine is not active. basicInfo: amount: 10 currency: GBP merchantRequestId: MERCHANT_CIT_002 transactionId: null transactionTimeUtc: null paymentInfo: amount: null currency: null nayaxTokenId: null siteId: null providerTransactionId: null decimalPlace: null '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Status' examples: badRequest: summary: Bad Request Example value: verdict: Declined code: 997 statusMessage: Did not receive mandatory parameters. '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Status' examples: unauthorized: summary: Unauthorized Example value: verdict: Declined code: 980 statusMessage: Unauthorized - Authentication failed. components: schemas: TransactionRequest: type: object description: >- Request body for processing a transaction (charge token, close transaction). properties: basicInfo: $ref: '#/components/schemas/BasicInfo' description: Basic transaction details. machineInfo: $ref: '#/components/schemas/MachineInfo' description: Information about the machine/terminal. validationKey: type: string nullable: true description: Validation key from the authentication flow. example: AUTH_KEY_FROM_VALIDATE cardHolderInfo: $ref: '#/components/schemas/CardHolderInfo' description: Cardholder details. additionalInfo: $ref: '#/components/schemas/AdditionalInfo' description: Additional information for the transaction and receipt. originalTransactionId: type: integer format: int32 description: >- Required for second-step transactions (e.g., refund, void). The original Nayax transaction ID. example: 123456 paymentInfo: $ref: '#/components/schemas/PaymentInfo' description: Payment-related information. additionalProperties: false TransactionResponse: type: object description: Response body for a transaction (charge token, close transaction). properties: status: $ref: '#/components/schemas/Status' description: Transaction status. basicInfo: $ref: '#/components/schemas/BasicInfo' description: >- Basic information about the transaction, including amount, currency, and merchant request ID. paymentInfo: $ref: '#/components/schemas/PaymentInfo' description: Payment-related information, including Nayax token ID if applicable. additionalProperties: false Status: type: object description: General status object for API responses. properties: verdict: type: string nullable: true description: Const string values 'Approved' or 'Declined'. example: Approved code: type: integer format: int32 description: Response code. 0 for Approved, relevant decline code for Declined. example: 0 statusMessage: type: string nullable: true maxLength: 255 description: >- Optional. Session status message free text field or additional varying data. example: Transaction processed successfully. customDeclineCode: type: string nullable: true description: >- Custom decline code, can also be used to return the HashedEcomTransactionId for validate-merchant success. example: 9515af0d6b5c328b6383ff241fa7b03e489d6285a8db6a4f0d8369e3f044e8d7 additionalProperties: false required: - verdict BasicInfo: type: object description: Basic information for a transaction. properties: sessionExpiration: type: string format: date-time nullable: true description: Session expiration date and time. example: '2025-12-31T23:59:59Z' redirectURL: type: string nullable: true description: URL where the shopper should be redirected after a redirection flow. example: https://your-merchant.com/callback amount: type: number format: double nullable: true description: Transaction amount. example: 15 currency: type: string nullable: true minLength: 3 maxLength: 3 description: The three-character ISO currency code according to ISO4217. example: USD countryCode: type: string nullable: true description: Country code according to ISO 3166. example: US requestType: $ref: '#/components/schemas/RequestType' description: Session transaction type. example: 0 entryMode: $ref: '#/components/schemas/EntryMode' description: |- Indicates the point-of-sale entry mode. For Initialize requests, values may be ECOM, COF or MOTO. For Payment requests, values may be MIT or CIT. example: 0 tokenModel: $ref: '#/components/schemas/TokenModel' description: >- Conditional (mandatory if EntryMode is COF). Indicates the desired token model. **Note on Token Behaviour**: A token's type (subscription/COF/top-up) is set during its initial creation and stored in our system. If a subsequent [Charge Token](ref:post_charge-token) request includes a different token type parameter, it is ignored. The system always uses the original token type from the initialization request, regardless of what is provided in later charge requests. example: 0 platform: $ref: '#/components/schemas/Platform' description: >- The platform from which the request originated (e.g., iOS, Android, Web). example: 0 isStoredCard: type: boolean nullable: true description: Optional. Cardholder approval for card saving. example: true cvc: type: integer format: int32 nullable: true description: Optional (for CIT only). Secure code for transaction verification. example: 123 token: type: string nullable: true description: >- Conditional (mandatory if EntryMode is MIT or CIT). Saved Card token (Nayax token ID). example: NAYAXTOK12345 merchantRequestId: type: string nullable: true description: >- The actor's/integrator's transaction ID. Will be passed as "MerchantTranId" in the SDK. example: MERCHANT_REQ_12345 transactionId: type: string nullable: true description: >- Conditional Nayax Transaction Identifier, required for second-step transactions (Refund etc.). example: NAYAXTRANS98765 transactionTimeUtc: type: string format: date-time nullable: true description: >- Conditional. Nayax Transaction Identifier for second-step transactions (Refund etc.). example: '2025-08-28T10:30:00Z' isSaveTokenWithoutConsent: type: boolean nullable: true description: >- Indicates if the token should be saved without explicit cardholder consent. example: false additionalProperties: false required: - amount - countryCode - requestType - entryMode - sessionExpiration - redirectURL MachineInfo: type: object description: Information about the machine or terminal. properties: machineId: type: string nullable: true description: Machine entity unique ID allocated in the Nayax Backoffice. example: '0434334921100366' additionalProperties: false required: - machineId CardHolderInfo: type: object description: Information about the cardholder. properties: cardholderCountry: type: string nullable: true description: Optional. Country of the cardholder. example: US paymentPageLan: type: string nullable: true description: Optional. Language for the payment page. example: en cardholderEmail: type: string nullable: true description: >- Optional (conditional - if COF, mandatory). Cardholder's email address. One of `cardholderEmail` or `cardHolderUniqId` needs to be provided. example: john.doe@example.com cardHolderUniqId: type: string nullable: true description: >- Optional (conditional - if MIT/CIT, mandatory). Unique identifier for the cardholder. One of `cardholderEmail` or `cardHolderUniqId` needs to be provided. example: unique_customer_id_123 brand: type: string nullable: true description: The brand of the card (e.g., VISA, MASTERCARD). example: VISA additionalProperties: false AdditionalInfo: type: object description: Additional data related to the transaction. properties: additionalData: type: string nullable: true description: >- Optional additional data in JSON format for the channel (iOS, Android, Web). example: '{"channel": "iOS", "campaignId": "XYZ789"}' additionalReceiptData: type: string nullable: true description: >- Optional additional data that the integrator wishes to be displayed in the eReceipt (new Weezmo eReceipt). example: >- [{"key":"productCode", "value":"PROD001"}, {"key":"customerRating", "value":"5_STARS"}] additionalProperties: false PaymentInfo: type: object description: Payment-related information. properties: amount: type: number format: double nullable: true description: Transaction amount. example: 15 authAmount: type: number format: double nullable: true description: Conditional (if requestType is Auth). The authorized amount. example: 15 currency: type: string nullable: true description: Currency code according to ISO4217. example: USD nayaxTokenId: type: string nullable: true description: Conditional (mandatory if COF). Saved Card token (Nayax token ID). example: NAYAXTOK12345 siteId: type: integer format: int32 nullable: true description: >- Site ID, identifying the region where the transaction originated in Nayax Servers. example: 1 providerTransactionId: type: string nullable: true description: Transaction ID from the Payment Service Provider (PSP). example: PSP_TRANS_ABC providerExternalData: type: string nullable: true description: Additional data from the PSP. example: '{"pspRef": "REF123", "riskScore": 10}' decimalPlace: type: integer format: int32 nullable: true description: >- The number of digits after the decimal point (e.g., amount = 100, decimalPlace = 2 --> amount for payment = 1.00). example: 2 additionalProperties: false required: - amount - currency RequestType: type: integer format: int32 description: Session Transaction Type. enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 x-enum-varnames: - Sale - Auth - Settlement - Void - Refund - PartialRefund - IncrementalAuth - CancelAuth - PartialCapture - AutoCapture - DelayAuth EntryMode: type: integer format: int32 description: Indicates the point-of-sale entry mode. enum: - 0 - 1 - 2 - 3 - 4 x-enum-varnames: - ECOM - MIT - CIT - COF - MOTO TokenModel: type: integer format: int32 description: >- Indicates the desired token model. **Note on Token Behaviour**: A token's type (subscription/COF/top-up) is set during its initial creation and stored in our system. If a subsequent [Charge Token](ref:post_charge-token) request includes a different token type parameter, it is ignored. The system always uses the original token type from the initialization request, regardless of what is provided in later charge requests. enum: - 0 - 1 - 2 x-enum-varnames: - StoredCard - Subscription - TopUp Platform: type: integer format: int32 description: Platform from which the request originated. enum: - 0 - 1 - 2 x-enum-varnames: - iOS - Android - Web securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT RSA token required for authentication. The token should be included in the `Authorization` header as `Bearer `. Nayax will issue tokens to the VAS, signed by a private key, and decrypt them using a public key. ````