openapi: 3.2.0
info:
  title: Vopay Debit Card Endpoints API
  version: '2.0'
  contact:
    name: API Support
    email: help@vopay.com
  description: 'Operations tagged Debit Card Endpoints across 2 of this provider''s published API definitions: vopay-payment-method-api-reference.json, vopay-payment-rails-api-reference.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://earthnode-dev.vopay.com/api/v2
tags:
- name: Debit Card Endpoints
paths:
  /debit-card/generate-embed-url:
    post:
      description: This endpoint is used to generate a unique URL to embed into your application using an iFrame. End users will use this to provide their card information, which can be used in the /debit-card/oct/push-funds and /debit-card/aft/pull-funds endpoint.
      summary: debit-card/generate-embed-url
      tags:
      - Debit Card Endpoints
      operationId: DebtiCardGenerateEmbedURLPOST
      deprecated: false
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                AccountID:
                  description: Your account ID
                  type: string
                Key:
                  description: API key for the account
                  type: string
                Signature:
                  description: Hashed signature for the request
                  type: string
                ClientAccountID:
                  description: When provided, the credit card added will be attached to the Client Account ID
                  type: string
                RedirectURL:
                  description: URL to redirect the user to after a card is added.
                  type: string
                RedirectMethod:
                  description: This parameter accepts InnerRedirect, OuterRedirect, and JavascriptMessage as parameter values.
                  type: string
                ClientControlled:
                  description: When set to true, the card added will be linked to your VoPay account. Default is false.
                  type: boolean
                CardTypeValidation:
                  description: When set to true, the card type will be validated to ensure the entered information represents a debit card. Default is false.
                  type: boolean
                Trigger3DS:
                  description: When set to true, 3DS authentication will be triggered during the card addition process. Default is false.
                  type: boolean
              required:
              - AccountID
              - Key
              - Signature
              - RedirectURL
        required: true
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: True if the request was successful, false if it failed
                    example: true
                  ErrorMessage:
                    type: string
                    description: Contains a description of the error if the request failed
                    example: ''
                  EmbedURL:
                    type: string
                    description: Custom generated iQ11 iframe url for users to use
                    example: https://earthnode-dev.vopay.com/iq11/embed/{Key Returned by Vopay}
                  IframeKey:
                    type: string
                    description: Unique key attached to the generated iFrame
                    example: a1b2c3
                required:
                - Success
                - ErrorMessage
                - EmbedURL
                - IframeKey
    servers:
    - url: https://earthnode-dev.vopay.com/api/v2
  /debit-card/delete:
    post:
      description: This endpoint allows you to delete a debit card associated with your VoPay account
      summary: debit-card/delete
      tags:
      - Debit Card Endpoints
      operationId: DebitCardDeletePOST
      deprecated: false
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                AccountID:
                  description: Your account ID
                  type: string
                Key:
                  description: API key for the account
                  type: string
                Signature:
                  description: Hashed signature for the request
                  type: string
                CardToken:
                  description: Debit card token
                  type: string
              required:
              - AccountID
              - Key
              - Signature
              - CardToken
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: True if the request was successful, false if it failed
                    example: true
                  ErrorMessage:
                    type: string
                    description: Contains a description of the error if the request failed
                    example: ''
                required:
                - Success
                - ErrorMessage
    servers:
    - url: https://earthnode-dev.vopay.com/api/v2
  /debit-card:
    get:
      description: This endpoint retrieves a list of debit cards associated with your VoPay account
      summary: debit-card
      tags:
      - Debit Card Endpoints
      operationId: DebitCardGET
      deprecated: false
      parameters:
      - name: AccountID
        in: query
        required: true
        description: Your account ID
        schema:
          type: string
      - name: Key
        in: query
        required: true
        description: API key for the account
        schema:
          type: string
      - name: Signature
        in: query
        required: true
        description: Hashed signature for the request
        schema:
          type: string
      - name: DebitCardToken
        in: query
        required: false
        description: When provided, this endpoint will only return the debit card associated with this token
        schema:
          type: string
      - name: ClientAccountID
        in: query
        required: false
        description: When provided, this endpoint will only return debit cards associated with this Client Account ID
        schema:
          type: string
      - name: ClientControlled
        in: query
        required: false
        description: When set to true, this endpoint will only return debit cards linked to your VoPay account. When set to false, it will return a list of your customer's debit cards.
        schema:
          type: boolean
      - name: 'Limit '
        in: query
        required: false
        description: Limit the number of records that are returned.
        schema:
          type: integer
      - name: 'Offset '
        in: query
        required: false
        description: Use this parameter to set the starting point in the dataset.
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: True if the request was successful, false if it failed
                    example: true
                  ErrorMessage:
                    type: string
                    description: Contains a description of the error if the request failed
                    example: ''
                  DebitCards:
                    type: object
                    description: 'Array serialized as a JSON object (JSON_FORCE_OBJECT): numeric string keys ''0'',''1'',... Empty {} when no items. Collection of the credit cards belonging to the account or client account'
                    properties:
                      '0':
                        type: object
                        properties:
                          DebitCardHolderName:
                            type: string
                            description: Debit card holder's name.
                            example: John Smith
                          DebitCardNumber:
                            type: string
                            description: Masked debit card number.
                            example: '*****1234'
                          DebitCardExpiryYear:
                            type: string
                            description: Expiry year of the debit card
                            example: '2023'
                          DebitCardExpiryMonth:
                            type: string
                            description: Expiry month of the debit card
                            example: '12'
                          DebitCardBrand:
                            type: string
                            description: Debit card brand
                            example: visa
                          DebitCardToken:
                            type: string
                            description: Debit card token.
                            example: ACBDF-GAFSHD-AHBS-123456
                          IsDefault:
                            type: boolean
                            description: Is this the VoPay account holder's default debit card
                            example: true
                          ClientAccountID:
                            type: string
                            description: ClientAccountID attached to the debit card.
                            example: ClientAccount1
                          SendingEligibility:
                            type: string
                            description: This debit card's eligibility to send funds.
                            example: '1'
                          ReceivingEligibility:
                            type: string
                            description: This debit card's eligibility to receive funds.
                            example: '1'
                          Type:
                            type: string
                            description: Verified card type.
                            example: debit
                          Brand:
                            type: string
                            description: Verified card brand.
                            example: mastercard
                          FundsAvailability:
                            type: string
                            description: Funds availability time frame after receiving a payment transaction.
                            example: immediate
                          InstitutionName:
                            type: string
                            description: Financial institution name.
                            example: bankcorp bank, the
                          InstitutionCountry:
                            type: string
                            description: Financial institution country.
                            example: usa
                          AccountStatementCurrency:
                            type: string
                            description: Currency of cardholder's account statement
                            example: usd
                          AcceptanceBrand:
                            type: string
                            description: Acceptance Brand
                            example: mcc
                          ProductType:
                            type: string
                            description: Product Type
                            example: consumer
                        required:
                        - DebitCardHolderName
                        - DebitCardNumber
                        - DebitCardExpiryYear
                        - DebitCardExpiryMonth
                        - DebitCardBrand
                        - DebitCardToken
                        - IsDefault
                        - ClientAccountID
                        - SendingEligibility
                        - ReceivingEligibility
                        - Type
                        - Brand
                        - FundsAvailability
                        - InstitutionName
                        - InstitutionCountry
                        - AccountStatementCurrency
                        - AcceptanceBrand
                        - ProductType
                    x-list-of: inline
                    x-empty-when: no debit cards match
                  Pagination:
                    type: object
                    description: Pagination metadata
                    properties:
                      TotalRecords:
                        type: string
                        description: Total number of debit card records in that search range.
                        example: '1000'
                      Offset:
                        type: string
                        description: Use this parameter to set the starting point in the dataset.
                        example: '1000'
                      Limit:
                        type: string
                        description: Limit the number of records that are returned.
                        example: '1000'
                    x-absent-when: response uses PaginationMetaData; present only when pagination is requested
                    required:
                    - TotalRecords
                    - Offset
                    - Limit
                required:
                - Success
                - ErrorMessage
                - DebitCards
    servers:
    - url: https://earthnode-dev.vopay.com/api/v2
  /debit-card/set-debit-card:
    post:
      description: This endpoint allows you to identify a debit card as belonging to the VoPay account holder. Optionally, you can use this endpoint to identify a debit card as being the VoPay account holder's default debit card. Note, a VoPay account can only have one default debit card.
      summary: debit-card/set-debit-card
      tags:
      - Debit Card Endpoints
      operationId: DebitCardSetDebitCardPOST
      deprecated: false
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                AccountID:
                  description: Your account ID
                  type: string
                Key:
                  description: API key for the account
                  type: string
                Signature:
                  description: Hashed signature for the request
                  type: string
                CardToken:
                  description: Debit card token
                  type: string
                ClientAccountID:
                  description: Client Account ID
                  type: string
                SetAsDefault:
                  description: Identify card as default debit card
                  type: boolean
              required:
              - AccountID
              - Key
              - Signature
              - CardToken
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: True if the request was successful, false if it failed
                    example: true
                  ErrorMessage:
                    type: string
                    description: Contains a description of the error if the request failed
                    example: ''
                  CardToken:
                    type: string
                    description: Debit card token
                    example: ACBDF-GAFSHD-AHBS-123456
                  IsDefault:
                    type: boolean
                    description: Is this the VoPay account holder's default debit card
                    example: true
                required:
                - Success
                - ErrorMessage
                - CardToken
                - IsDefault
    servers:
    - url: https://earthnode-dev.vopay.com/api/v2
  /debit-card/default-debit-card:
    get:
      description: This endpoint retrieves the default debit card associated with your VoPay account
      summary: debit-card/default-debit-card
      tags:
      - Debit Card Endpoints
      operationId: DebitCardDefaultDebitCardGET
      deprecated: false
      parameters:
      - name: AccountID
        in: query
        required: true
        description: Your account ID
        schema:
          type: string
      - name: Key
        in: query
        required: true
        description: API key for the account
        schema:
          type: string
      - name: Signature
        in: query
        required: true
        description: Hashed signature for the request
        schema:
          type: string
      - name: ClientAccountID
        in: query
        required: false
        description: When provided, this endpoint will return the default debit card associated with this Client Account ID
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: True if the request was successful, false if it failed
                    example: true
                  ErrorMessage:
                    type: string
                    description: Contains a description of the error if the request failed
                    example: ''
                  DefaultPushToCard:
                    type: object
                    description: 'Array serialized as a JSON object (JSON_FORCE_OBJECT): numeric string keys ''0'',''1'',... Empty {} when no items. Default debit card associated with the Account or Client Account'
                    properties:
                      '0':
                        type: object
                        properties:
                          PushToCardToken:
                            type: string
                            description: A unique token associated with the debit card.
                            example: ACBDF-GAFSHD-AHBS-123456
                          CardHolderName:
                            type: string
                            description: Debit card holder name.
                            example: Natalie Merchant
                          CardNumber:
                            type: string
                            description: Masked debit card number.
                            example: '**** **** **** 1234'
                          CardExpiryYear:
                            type: string
                            description: Expiry year of debit card.
                            example: '2022'
                          CardExpiryMonth:
                            type: string
                            description: Expiry month of debit card.
                            example: '03'
                          CardBrand:
                            type: string
                            description: Debit card brand
                            example: visa
                        required:
                        - PushToCardToken
                        - CardHolderName
                        - CardNumber
                        - CardExpiryYear
                        - CardExpiryMonth
                        - CardBrand
                    x-list-of: inline
                    x-empty-when: no default debit card
                required:
                - Success
                - ErrorMessage
                - DefaultPushToCard
    servers:
    - url: https://earthnode-dev.vopay.com/api/v2
  /debit-card/oct/push-funds:
    post:
      description: "This endpoint is used to instantly send funds from your VoPay account to the debit card linked to the provided CardToken.\n\n If a ClientAccountID is provided, the client account's default card will be used for the transaction.\n\nNote: You must first generate a CardToken using the /debit-card/generate-embed-url endpoint."
      summary: debit-card/oct/push-funds
      tags:
      - Debit Card Endpoints
      operationId: OCTPushFundsPOST
      deprecated: false
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                AccountID:
                  description: Your account ID
                  type: string
                Key:
                  description: API key for the account
                  type: string
                Signature:
                  description: Hashed signature for the request
                  type: string
                ClientAccountID:
                  description: Client Account ID
                  type: string
                CardToken:
                  description: The token identifying the debit card to charge (returned from /debit-card/generate-embed-url).
                  type: string
                Amount:
                  description: The amount to send to the customer's debit card.
                  type: number
                Currency:
                  description: 3 character currency code for the currency to sent to the customer's debit card. If this is not specified the transaction will use the account's local currency (CAD).
                  type: string
                IdempotencyKey:
                  description: A unique key which the server can use to recognize and reject subsequent retries of the same request.
                  type: string
                ParentTransactionID:
                  description: The parent transaction where the withdrawal will be linked to, can become a split payment with multiple withdrawals. When funds of the parent transaction have been released the system will generate the distributions of these funds automatically.
                  type: string
                GLCode:
                  description: An optional unique identification general ledger code.
                  type: string
                TransactionTypeCode:
                  description: CPA transaction code. Use the /api/v2/account/transactions/codes endpoint to retrieve a list of valid transaction codes. If not specified, the transaction will be created using code 450 (miscellaneous).
                  type: string
              required:
              - AccountID
              - Key
              - Signature
              - CardToken
              - Amount
        required: true
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: True if the request was successful, false if it failed
                    example: true
                  ErrorMessage:
                    type: string
                    description: Contains a description of the error if the request failed
                    example: ''
                  TransactionID:
                    type: integer
                    description: The unique ID of the transaction that was just submitted.
                    example: '1122'
                required:
                - Success
                - ErrorMessage
                - TransactionID
    servers:
    - url: https://earthnode-dev.vopay.com/api/v2
  /debit-card/oct/transaction:
    get:
      description: This method is used to look up and return the full details on a single OCT transaction. OCT transactions sends money from your VoPay account directly onto the customer's debit card.
      summary: debit-card/oct/transaction
      tags:
      - Debit Card Endpoints
      operationId: OCTPushFundsTransactionsGET
      deprecated: false
      parameters:
      - name: AccountID
        in: query
        required: true
        description: Your account ID
        schema:
          type: string
      - name: Key
        in: query
        required: true
        description: API key for the account
        schema:
          type: string
      - name: Signature
        in: query
        required: true
        description: Hashed signature for the request
        schema:
          type: string
      - name: TransactionID
        in: query
        required: true
        description: Account transaction ID
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: True if the request was successful, false if it failed
                    example: true
                  ErrorMessage:
                    type: string
                    description: Contains a description of the error if the request failed
                    example: ''
                  TransactionID:
                    type: integer
                    description: The unique ID of the transaction
                    example: '1122'
                  TransactionStatus:
                    type: string
                    description: 'A message indicating the current transaction status. Statuses are: successful, failed, rejected'
                    example: successful
                  TransactionDateTime:
                    type: string
                    format: date-time
                    description: The timestamp when the transaction was created
                    example: '2019-11-01 12:00:00'
                  Amount:
                    type: number
                    description: The dollar amount of the transaction. This is the amount that was sent to the customer's debit card.
                    example: '2000'
                  Currency:
                    type: string
                    description: The currency for the transaction.
                    example: CAD
                  PushToCardToken:
                    type: string
                    description: A unique token who has the card information. Note. For security purposes we do not store the customer debit card information.
                    example: ACBDF-GAFSHD-AHBS-123456
                  Country:
                    type: string
                    description: Customer's Country specified using full country name or ISO 3166-1 alpha-2 code.
                    example: CA
                  LastModified:
                    type: string
                    format: date-time
                    description: This timestamp indicates when the transaction record was last modified. In normal circumstances the transaction record will only be modified when the status of the transaction changes.
                    example: '2023-11-03 01:00:00'
                  GLCode:
                    type: string
                    description: General ledger code.
                    example: '4300'
                  TransactionTypeCode:
                    type: string
                    description: CPA transaction code.
                    example: '999'
                required:
                - Success
                - ErrorMessage
                - TransactionID
                - TransactionStatus
                - TransactionDateTime
                - Amount
                - Currency
                - PushToCardToken
                - Country
                - LastModified
                - GLCode
                - TransactionTypeCode
    servers:
    - url: https://earthnode-dev.vopay.com/api/v2
  /debit-card/aft/pull-funds:
    post:
      description: "This endpoint is used to instantly pull funds from your debit card linked to the provided CardToken to fund your VoPay account.\n\n If a ClientAccountID is provided, the client account's default card will be used for the transaction.\n\nNote: You must first generate a CardToken using the /debit-card/generate-embed-url endpoint."
      summary: debit-card/aft/pull-funds
      tags:
      - Debit Card Endpoints
      operationId: AFTPullFundsPOST
      deprecated: false
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                AccountID:
                  description: Your account ID
                  type: string
                Key:
                  description: API key for the account
                  type: string
                Signature:
                  description: Hashed signature for the request
                  type: string
                ClientAccountID:
                  description: Client Account ID
                  type: string
                CardToken:
                  description: The token identifying the debit card to charge (returned from /debit-card/generate-embed-url).
                  type: string
                Amount:
                  description: The amount to send to the customer's debit card.
                  type: number
                Currency:
                  description: 3 character currency code for the currency to sent to the customer's debit card. If this is not specified the transaction will use the account's local currency (CAD).
                  type: string
                IdempotencyKey:
                  description: A unique key which the server can use to recognize and reject subsequent retries of the same request.
                  type: string
                GLCode:
                  description: An optional unique identification general ledger code.
                  type: string
              required:
              - AccountID
              - Key
              - Signature
              - CardToken
              - Amount
        required: true
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: True if the request was successful, false if it failed
                    example: true
                  ErrorMessage:
                    type: string
                    description: Contains a description of the error if the request failed
                    example: ''
                  TransactionID:
                    type: integer
                    description: The unique ID of the transaction that was just submitted.
                    example: '1122'
                required:
                - Success
                - ErrorMessage
                - TransactionID
    servers:
    - url: https://earthnode-dev.vopay.com/api/v2
  /debit-card/aft/transaction:
    get:
      description: This method is used to look up and return the full details on a single AFT transaction. AFT transactions pull money from you debit card directly into your VoPay account .
      summary: debit-card/aft/transaction
      tags:
      - Debit Card Endpoints
      operationId: AFTPullFundsTransactionsGET
      deprecated: false
      parameters:
      - name: AccountID
        in: query
        required: true
        description: Your account ID
        schema:
          type: string
      - name: Key
        in: query
        required: true
        description: API key for the account
        schema:
          type: string
      - name: Signature
        in: query
        required: true
        description: Hashed signature for the request
        schema:
          type: string
      - name: TransactionID
        in: query
        required: true
        description: Account transaction ID
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                type: object
                properties:
                  Success:
                    type: boolean
                    description: True if the request was successful, false if it failed
                    example: true
                  ErrorMessage:
                    type: string
                    description: Contains a description of the error if the request failed
                    example: ''
                  TransactionID:
                    type: integer
                    description: The unique ID of the transaction
                    example: '1122'
                  TransactionStatus:
                    type: string
                    description: 'A message indicating the current transaction status. Statuses are: successful, failed, rejected'
                    example: successful
                  TransactionDateTime:
                    type: string
                    format: date-time
                    description: The timestamp when the transaction was created
                    example: '2019-11-01 12:00:00'
                  Amount:
                    type: number
                    description: The dollar amount of the transaction. This is the amount that was sent to the customer's debit card.
                    example: '2000'
                  Currency:
                    type: string
                    description: The currency for the transaction.
                    example: CAD
                  PushToCardToken:
                    type: string
                    description: A unique token who has the card information. Note. For security purposes we do not store the customer debit card information.
                    example: ACBDF-GAFSHD-AHBS-123456
                  Country:
                    type: string
                    description: Customer's Country specified using full country name or ISO 3166-1 alpha-2 code.
                    example: CA
                  GLCode:
                    type: string
                    description: General ledger code.
                    example: '4300'
                  LastModified:
                    type: string
                    format: date-time
                    description: This timestamp indicates when the transaction record was last modified. In normal circumstances the transaction record will only be modified when the status of the transaction changes.
                    example: '2023-11-03 01:00:00'
                required:
                - Success
                - ErrorMessage
                - TransactionID
                - TransactionStatus
                - TransactionDateTime
                - Amount
                - Currency
                - PushToCardToken
                - Country
                - GLCode
                - LastModified
    servers:
    - url: https://earthnode-dev.vopay.com/api/v2
x-refined-from:
- vopay-payment-method-api-reference.json
- vopay-payment-rails-api-reference.json