> ## Documentation Index > Fetch the complete documentation index at: https://docs.payaza.africa/llms.txt > Use this file to discover all available pages before exploring further. # Create Subscription > This endpoint creates a new subscription for a customer, enrolls the customer's card, and initiates the first payment where applicable. ### Important Notes * **`cardDetails`** is mandatory when creating a subscription. * If no trial period is configured, the first charge is attempted immediately after the card is enrolled. * If a trial period is configured, the subscription is created with a status of **TRIALING**. The card is enrolled immediately, but the first charge is deferred until the trial period ends. * When additional customer authentication is required, the subscription is created with a status of **REQUIRES_ACTION**, and the response includes the 3D Secure challenge details. * Creating another active subscription using the same `customerId` and `planCode` returns a **409 Conflict** response. * Before the first successful payment, the subscription remains in the **INCOMPLETE** state. * The card service determines the charge mode (**DIRECT_CHARGE**, **TOKENIZATION**, or **AGREEMENT_BASED**) during card enrollment and returns it in the response. The subscription service stores this value for future recurring billing. ## OpenAPI ````yaml /openapi.json post /subscription/api/v1/subscriptions openapi: 3.0.1 info: title: Payaza Documentation version: 2.0.0 description: >- API reference for processing payments using Card, Bank Transfer, USSD, and QR Code methods. servers: - url: https://api.payaza.africa/live security: - ApiKeyAuth: [] - TenantID: [] - ProductID: [] tags: - name: Transfers description: >- Transfers are transactions made from your Payaza account to beneficiaries. Merchants can instantly transfer funds from their available balance. For every transfer, you need to specify the amount and the beneficiary’s details. You become eligible to make transfers after you have been verified. (you sign up, finish account activation and KYC verification). - name: Payaza Account description: >- This is our internal account that can be used to make payouts to other bank accounts, in single or in bulk. The Payaza account can also be used to receive settlements. It can also be used to track the transfer status of your transactions and check your balance instantly - name: Sub Accounts description: >- This enables you to establish Sub Payaza accounts for your customers. Each sub-account comes with an assigned static virtual account, facilitating direct funding for individual accounts. Furthermore, the Main Payaza account can directly initiate funding for each sub-account. These sub-accounts serve the purpose of managing unique account positions or balances and facilitating disbursements from these positions to specified beneficiaries. - name: EUR Accounts description: >- This endpoints enable you to create EUR subaccounts which can be used to make transfers as required . - name: Apple Pay and Google Pay description: >- Apple Pay and Google Pay give your customers a fast, familiar, and secure way to complete payments. Our APIs provide a gateway to provide these services to your users for a smooth payment experience. - name: Virtual Accounts description: >- Virtual Accounts are bank accounts that are created for a specific purpose and last for specified durations. Virtual accounts are issued by Payaza’s partner banks. Our virtual account APIs can be used to create virtual accounts and perform other tasks relevant to virtual accounts. Virtual accounts are created to foster easy payment collections for your business and platform. Static/Reserved Account: This virtual account is created by the merchant and remains valid indefinitely. It can be used multiple times and does not expire. Dynamic Account: This virtual account is generated for a specific transaction or purpose. Please note that dynamic virtual account remains valid for a temporary period of time or until a payment of the specified amount is received. Upon expiry, a merchant can generate another one for a different purpose. - name: Card Collection description: >- The Card Collection APIs can be used to make card transactions, refund transactions that have been performed, check the status of a transaction and so much more. - name: Card Tokenisation description: >- The Card Tokenisation APIs are used to create card tokens, charge cards using tokens, retrieve all tokens created by a merchant account and deleting any card token as desired. - name: Refunds And Chargebacks description: >- The Refunds and Chargeback APIs are used to initiate refunds, view your refund and chargeback history and so much more. - name: Branches description: >- The Refunds and Chargeback APIs are used to initiate refunds, view your refund and chargeback history and so much more. - name: Auth-Capture-Void description: >- The Auth-Capture-Void APIs provide a two-phase payment process where transactions are first authorized, then captured or voided. This allows merchants to hold funds and complete the transaction in the future. - name: Momo and ZAR Collections description: APIs for MoMo, ZAR and XOF collections. - name: Check Transaction Status(Merchant Reference) description: >- This endpoint is used to check the transaction status of a transaction using the Merchant Reference.. paths: /subscription/api/v1/subscriptions: post: tags: - Subscriptions summary: Create Subscription description: >- This endpoint creates a new subscription for a customer, enrolls the customer's card, and initiates the first payment where applicable. ### Important Notes * **`cardDetails`** is mandatory when creating a subscription. * If no trial period is configured, the first charge is attempted immediately after the card is enrolled. * If a trial period is configured, the subscription is created with a status of **TRIALING**. The card is enrolled immediately, but the first charge is deferred until the trial period ends. * When additional customer authentication is required, the subscription is created with a status of **REQUIRES_ACTION**, and the response includes the 3D Secure challenge details. * Creating another active subscription using the same `customerId` and `planCode` returns a **409 Conflict** response. * Before the first successful payment, the subscription remains in the **INCOMPLETE** state. * The card service determines the charge mode (**DIRECT_CHARGE**, **TOKENIZATION**, or **AGREEMENT_BASED**) during card enrollment and returns it in the response. The subscription service stores this value for future recurring billing. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/createSubscriptionRequest' examples: Create Subscription Plan: summary: Create Subscription value: customerId: test-trial customerEmail: johndoe@gmail.com planCode: PLN_906FE4B cardDetails: cardNumber: 554656xxxxxx742 expiryMonth: '01' expiryYear: '02' securityCode: '123' cardHolderName: John Doe present: true responses: '200': description: Subscription Created content: application/json: schema: $ref: '#/components/schemas/createSubscriptionResponse' examples: Create Subscription(Successful): summary: Successful Subscription value: success: true message: Subscription created data: subscription: id: 132 businessFk: 16296 planId: 86 customerId: a1a4bfc6-fff4-470b-672df-53db3327cc6er customerEmail: danieleakinola@gmail.com subscriptionMode: null payazaTokenReference: null agreementId: null vaultReference: null mandateReference: null customerAuthorizedAt: '2026-06-30T04:07:02.338683' pendingPlanId: null status: ACTIVE currentPeriodStart: '2026-06-30T04:07:02.338683' currentPeriodEnd: '2026-07-30T04:07:06.026488' nextChargeDate: '2026-07-30T04:07:06.026488' trialEndDate: null pauseResumesAt: null cancelAt: '2026-09-20T00:00:00' cancelledAt: null cancellationReason: null cardExpiryAlertSent: false connectionMode: Live enrollmentReference: SUBREF_72B4051E427E4BA49D enrollmentTxnReference: SUB_ENROLL_132_1782788822736 chargeMode: DIRECT_CHARGE metadata: null createdAt: '2026-06-30T04:07:02.339296' updatedAt: '2026-06-30T04:07:06.194315' chargeResult: status: SUCCESS amount: 200 currency: NGN transactionReference: SUB_ENROLL_132_1782788822736 authCode: '' chargeMode: DIRECT_CHARGE message: Your card has been saved successfully. Create Subscription(Successful -Trial Subscription): summary: Create Subscription(Successful - Trial Subscription) value: success: true message: Subscription created data: subscription: id: 21 customerId: test-trial customerEmail: johndoe@gmail.com firstName: null lastName: null customerAuthorizedAt: null status: ACTIVE currentPeriodStart: '2026-07-08T19:38:15.229726' currentPeriodEnd: '2026-07-09T19:38:18.292411' nextChargeDate: '2026-07-09T19:38:18.292411' trialEndDate: null pauseResumesAt: null cancelAt: null pausedAt: null cancelledAt: null cancellationReason: null cardExpiryAlertSent: false connectionMode: Live enrollmentReference: SUBREF_FF29C28B70034065A6 enrollmentTxnReference: SUB_ENROLL_21_1783539495235 chargeMode: DIRECT_CHARGE metadata: null createdAt: '2026-07-08T19:38:15.22973' updatedAt: '2026-07-08T19:38:18.295641' customerBearsFee: false enrollConfirmed: true chargeResult: charged: true status: SUCCESS amount: 1000 fees: 0 currency: NGN transactionReference: SUB_ENROLL_21_1783539495235 authCode: '581410' chargeMode: DIRECT_CHARGE message: Approved '400': description: Invalid request security: - ApiKeyAuth: - Payaza {{Public API Key In Base64}} components: schemas: createSubscriptionRequest: title: Create Subscription Request type: object required: - customerId - customerEmail - planCode - cardDetails properties: customerId: type: string description: The unique reference identifier assigned to the customer. example: test-trial customerEmail: type: string format: email description: >- The email address of the customer used for transactional notifications. example: johndoe@gmail.com planCode: type: string description: >- The unique plan code generated when the subscription plan was created. If omitted, a plan is automatically created from the request. example: PLN_906FE4B cardDetails: type: object description: >- The card information used to enroll the customer for recurring billing. required: - cardNumber - expiryMonth - expiryYear - securityCode - cardHolderName - present properties: cardNumber: type: string description: The primary account number (PAN) of the credit or debit card. example: 554656xxxxxx742 expiryMonth: type: string description: The two-digit format card expiration month. example: '01' expiryYear: type: string description: The two-digit format card expiration year. example: '02' securityCode: type: string description: The 3 or 4 digit card verification value (CVV/CVC) code. example: '123' cardHolderName: type: string description: The full legal name printed on the card face. example: John Doe present: type: boolean description: To validate the card details. example: true createSubscriptionResponse: title: Create Subscription Response type: object properties: success: type: boolean description: Indicates if the request was successful. example: true message: type: string description: Descriptive message regarding the subscription creation status. example: Subscription created data: type: object description: >- The payload containing the combined results of the subscription enrollment and initialization charge. properties: subscription: type: object description: Detailed entity information for the newly enrolled subscription. properties: id: type: integer description: Unique internal identifier for the subscription. example: 20 customerId: type: string description: Unique identifier assigned to the customer. example: johndoe customerEmail: type: string format: email description: Email address of the customer. example: johndoe@gmail.com firstName: type: string nullable: true description: First name of the customer. example: null lastName: type: string nullable: true description: Last name of the customer. example: null customerAuthorizedAt: type: string format: date-time nullable: true description: >- Timestamp indicating when the customer explicitly authorized billing. example: null status: type: string description: The current lifecycle status of the subscription. example: ACTIVE currentPeriodStart: type: string format: date-time description: Timestamp indicating when the current billing window opened. example: '2026-07-08T19:35:52.348327' currentPeriodEnd: type: string format: date-time description: Timestamp indicating when the current billing window closes. example: '2026-08-08T19:35:55.569925' nextChargeDate: type: string format: date-time description: The next scheduled auto-billing execution timestamp. example: '2026-08-08T19:35:55.569925' trialEndDate: type: string format: date-time nullable: true description: Timestamp identifying when the free trial period lapses. example: null pauseResumesAt: type: string format: date-time nullable: true description: >- Timestamp representing when a paused schedule automatically restarts. example: null cancelAt: type: string format: date-time nullable: true description: Scheduled timestamp for future termination. example: null pausedAt: type: string format: date-time nullable: true description: Timestamp recording when the schedule was paused. example: null cancelledAt: type: string format: date-time nullable: true description: Timestamp recording absolute termination. example: null cancellationReason: type: string nullable: true description: Contextual reasoning note for termination. example: null cardExpiryAlertSent: type: boolean description: >- Indicates if an alert was fired concerning upcoming card expiration. example: false connectionMode: type: string description: The environment mode context. example: Live enrollmentReference: type: string description: >- The global token signature identifying the authorized card reference. example: SUBREF_BFE417ABF6FF49A985 enrollmentTxnReference: type: string description: >- Transaction baseline reference tracking the enrollment event. example: SUB_ENROLL_20_1783539352354 chargeMode: type: string description: The engine mechanism managing core billing execution. example: DIRECT_CHARGE metadata: type: object nullable: true description: Custom variable pairs appended to the reference record. example: null createdAt: type: string format: date-time description: Record creation baseline logging. example: '2026-07-08T19:35:52.34833' updatedAt: type: string format: date-time description: Record tracking modification context log. example: '2026-07-08T19:35:55.573662' customerBearsFee: type: boolean description: >- Defines if clearing fees process directly on the subscriber layer. example: false enrollConfirmed: type: boolean description: >- Confirms card setup authorization verified with provider infrastructure. example: true chargeResult: type: object description: >- Realtime transaction processing outcome details for the initial subscription authorization charge. properties: charged: type: boolean description: >- Identifies if transaction processing completed a financial collection transfer. example: true status: type: string description: The operational outcome status state signature. example: SUCCESS amount: type: number description: The transaction amount computed. example: 100 fees: type: number description: >- Processing fee costs attributed during authorization extraction. example: 0 currency: type: string description: The 3-letter ISO code denoting currency context. example: NGN transactionReference: type: string description: >- Unique ledger identification token identifying the payment attempt. example: SUB_ENROLL_20_1783539352354 authCode: type: string description: Bank network approval code verification key. example: '581032' chargeMode: type: string description: Operational routing signature code utilized. example: DIRECT_CHARGE message: type: string description: >- Human-readable processor outcome statement code clear text response. example: Approved securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: Payaza {{Public API Key in Base 64}} TenantID: type: apiKey in: header name: X-TenantID description: live or test ProductID: type: apiKey in: header name: X-ProductID description: 'default value is ‟app” ' ````