> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payfonte.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit Card PIN

> Submit the card PIN when a card payment response returns `action` as `pin`. Sandbox card test data is available in [Testing](https://docs.payfonte.com/en/guides/introductions/testing#card-test-details).



## OpenAPI

````yaml /api-reference/openapi-3.1.yml post /payments/v1/cards/pin
openapi: 3.1.0
info:
  title: Payfonte - OpenAPI 3.1
  description: >-
    This is the minimal API for payfonte collection and disbursements API. To
    view a more elaborate documentation see here.


    Some useful links:

    - [Home](https://payfonte.com)

    - [Payfonte Documentation](https://docs.payfonte.com)
  termsOfService: https://www.payfonte.com/terms
  contact:
    email: tech@payfonte.com
  version: 1.0.0
servers:
  - url: https://sandbox-api.payfonte.com
    description: Sandbox API Base URL
  - url: https://api.payfonte.com
    description: Production API Base URL
security:
  - clientId: []
    clientSecret: []
tags:
  - name: Collections
    description: Everything about your payment collection with payfonte
    externalDocs:
      description: Find out more
      url: https://docs.payfonte.com/#/collections/inline
  - name: Card Collections
    description: Everything about your card payment collections with payfonte
  - name: Disbursements
    description: >
      Find full list of supported Disbursement providers here [Supported
      Providers](https://docs.payfonte.com/#/Disbursements/supported-Disbursements)

      There are 3 main process to carry out a Disbursement on Payfonte

      1. Validate A transfer Recipient

      2. Initiate a Disbursement Request

      3. Verify a Disbursement Request
  - name: Wallets
    description: >-
      A Little bit about our [wallets here]
      (https://docs.payfonte.com/#/introductions/wallets)
paths:
  /payments/v1/cards/pin:
    post:
      tags:
        - Card Collections
      summary: Submit Card PIN
      description: >-
        Submit the card PIN when a card payment response returns `action` as
        `pin`. Sandbox card test data is available in
        [Testing](https://docs.payfonte.com/en/guides/introductions/testing#card-test-details).
      operationId: submitCardPin
      requestBody:
        description: Card PIN request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardPaymentPinRequest'
            example:
              reference: DCD20260701144120NCDZW
              provider: card-nigeria
              card:
                pan: 5061 4604 1012 1111 106
                expiry:
                  month: '12'
                  year: '2050'
                cvv: '562'
                pin: '1106'
                cardHolderName: Donna Flatley
        required: true
      responses:
        '200':
          description: Card payment requires the next customer action or verification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardPaymentActionEnvelope'
              examples:
                pin:
                  summary: PIN required
                  value:
                    statusCode: 200
                    data:
                      reference: DCD20260701133425EIQWF
                      action: pin
                      data: {}
                verification:
                  summary: Verification required
                  value:
                    statusCode: 200
                    data:
                      reference: DCD20260701133425EIQWF
                      action: verification
                      data: {}
        '201':
          description: Card payment requires the next customer action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardPaymentActionEnvelope'
              examples:
                otp:
                  summary: OTP required
                  value:
                    statusCode: 201
                    data:
                      reference: DCD20260701133425EIQWF
                      action: otp
                      data: {}
                redirect:
                  summary: 3DS redirect required
                  value:
                    statusCode: 201
                    data:
                      reference: DCD20260701144120NCDZW
                      action: redirect
                      data:
                        redirectURL: https://s.6bd.co/card-3ds/mce1aN
components:
  schemas:
    CardPaymentPinRequest:
      required:
        - reference
        - provider
        - card
      type: object
      properties:
        reference:
          type: string
          description: Card payment reference returned by the previous card payment step.
          example: DCD20260701144120NCDZW
        provider:
          type: string
          description: Card provider slug.
          example: card-nigeria
        card:
          $ref: '#/components/schemas/CardPaymentPinCard'
    CardPaymentActionEnvelope:
      required:
        - statusCode
        - data
      type: object
      properties:
        statusCode:
          type: integer
          description: Application status code returned in the response body.
          example: 200
        data:
          $ref: '#/components/schemas/CardPaymentActionResponse'
    CardPaymentPinCard:
      allOf:
        - $ref: '#/components/schemas/CardPaymentCard'
        - required:
            - pin
          type: object
          properties:
            pin:
              type: string
              description: Card PIN required to continue the transaction.
              example: '1106'
    CardPaymentActionResponse:
      required:
        - reference
        - action
        - data
      type: object
      properties:
        reference:
          type: string
          description: >-
            Card payment reference to use in the next card step or verification
            request.
          example: DCD20260701133425EIQWF
        action:
          type: string
          description: Next action required to continue or verify the card payment.
          enum:
            - pin
            - otp
            - redirect
            - verification
          example: pin
        data:
          $ref: '#/components/schemas/CardPaymentActionData'
    CardPaymentCard:
      required:
        - pan
        - expiry
        - cvv
        - cardHolderName
      type: object
      properties:
        pan:
          type: string
          description: Card primary account number.
          example: 5061 4604 1012 1111 102
        expiry:
          $ref: '#/components/schemas/CardPaymentExpiry'
        cvv:
          type: string
          description: Card security code.
          example: '558'
        cardHolderName:
          type: string
          description: Name printed on the card.
          example: Emily Heidenreich-Kohler
    CardPaymentActionData:
      type: object
      properties:
        redirectURL:
          type: string
          format: uri
          description: >-
            URL where the customer should complete 3DS authentication when
            `action` is `redirect`.
          example: https://s.6bd.co/card-3ds/mce1aN
    CardPaymentExpiry:
      required:
        - month
        - year
      type: object
      properties:
        month:
          type: string
          description: Two-digit card expiry month.
          example: '12'
        year:
          type: string
          description: Four-digit card expiry year.
          example: '2050'
  securitySchemes:
    clientId:
      type: apiKey
      name: client-id
      in: header
    clientSecret:
      type: apiKey
      name: client-secret
      in: header

````