openapi: 3.0.3 info: title: IngoPay API — Verify Retail Card-Present description: > Verify support for customer card or bill payment account data at a physical retail location and tokenize the account for use in a subsequent Process call. This spec covers retail card-present verification for card (`CA`) and bill payment (`BP`) account types. **`account_type` determines the payment type:** - `CA` — Debit or credit card (card-present). Requires raw card fields including `account`, `expiration_date`, and optionally `cvv`. - `BP` — Bill payment (card-present). Requires `payee_id` and `account`. `expiration_date` and `cvv` are not applicable. **Client configuration determines field requirements:** - `store_id`, `clerk_id`, `terminal_id` — Required when the client is configured as a retail participant (`retail` flag enabled in client configuration). Always provide these for card-present integrations. - `cvv` and `expiration_date` — Conditionally required for `CA` based on client configuration (`cvv_enabled`, `expiration_date_enabled` flags). Contact your Ingo integration manager to confirm your configuration. **Mutual exclusivity rules:** - Provide either `customer_account_token` **or** raw account fields — never both. > **Note:** `retail_location{}` is not validated at the Verify stage. It is only enforced at the Process stage for `CA` account type when the `retail_object` flag is enabled in client configuration. version: '11' contact: name: Ingo Money Developer Support url: https://developers.ingomoney.com servers: - url: https://payapi-sandbox.ingo.money description: Sandbox - url: https://payapi.ingo.money description: Production paths: /gateway/verify--retail: post: summary: Verify and tokenize an account at a retail card-present terminal description: > Validates a customer's card or bill payment account at a physical retail location and returns a `customer_account_token` for use in push (Process) requests. Set `account_type` to `CA` for card or `BP` for bill payment. operationId: verifyRetailCardPresent tags: - Account Tokenization requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VerifyRetailCardPresentRequest' examples: card_present_ca: summary: Card present — account_type CA value: participant_id: 12345 account_type: CA amount: 101 recipient_first_name: Alex recipient_last_name: Rivera account: 411111XXXXXXXXXX expiration_date: '2612' cvv: '123' recipient_address1: 100 Innovation Way recipient_address2: Apt 3 recipient_city: Anytown recipient_state: GA recipient_zip: '00000' recipient_phone: '1231231234' store_id: STORE-001 terminal_id: TERM-042 clerk_id: CLK-007 participant_unique_id1: fb746578-c4c3-498f-b398-1ff07b4fe2ff participant_unique_id2: 77d6b010-eab4-44dc-9a27-6ffa4838c9f2 timestamp: 1579832224 version: 11 card_present_bp: summary: Card present — account_type BP value: participant_id: 12345 account_type: BP payee_id: '123457' amount: 1010.5 account: '12345678' recipient_first_name: Alex recipient_last_name: Rivera recipient_address1: 100 Innovation Way recipient_address2: Apt 2 recipient_city: Anytown recipient_state: GA recipient_zip: '00000' recipient_phone: '1231231234' store_id: STORE-001 terminal_id: TERM-042 clerk_id: CLK-007 participant_unique_id1: f8f68709-8e5d-4c19-8ca0-2eaffef4ec57 participant_unique_id2: 257b5bae-d52f-42e2-8f2c-0700d8d7a7a5 timestamp: 1587052132 version: 11 responses: '200': description: Verification successful — token returned content: application/json: schema: $ref: '#/components/schemas/VerifyRetailCardPresentResponse' example: status: 100 client_message: Success data: customer_account_token: 715b9903-7bcd-45ae-bc92-4092c8186d9f last_4: '1111' request_timestamp: 1579832224 issuers: - payee_id: '526263' payee_name: Bank of America - Platinum MasterCard and Visa payee_address: PO Box 15019 payee_city: Wilmington payee_state: DE payee_zip: 19850-5019 credit_info: min: '0.05' max: '1500.00' card_type: Debit estimated_posting_time: Payment will post Next Business Day estimated_posting_date: 04/22/2026 issuing_network: Visa credit_enabled: 1 debit_enabled: 0 participant_unique_id1: fb746578-c4c3-498f-b398-1ff07b4fe2ff participant_unique_id2: 77d6b010-eab4-44dc-9a27-6ffa4838c9f2 expiration_date: '2612' count: 1 time: '4.0146' '400': description: Validation error — check request body content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: 700 client_message: Account not currently available for payment data: request_timestamp: 1579832224 components: schemas: VerifyRetailCardPresentRequest: type: object required: - participant_id - account_type - participant_unique_id1 - timestamp - version description: > Provide either `customer_account_token` or raw account fields. For `BP` account type, also provide `payee_id`. `store_id`, `clerk_id`, and `terminal_id` are required when the client is configured as a retail participant — confirmed via client-level backend configuration. properties: participant_id: type: integer description: Unique participant identifier assigned by Ingo. example: 12345 account_type: type: string enum: - CA - BP minLength: 1 description: > `CA` = card-present (debit or credit), `BP` = bill payment card-present. example: CA payee_id: type: string maxLength: 40 description: > Ingo assigned payee ID for the selected biller. Required for `BP` account type. Obtain from the Biller Payments Search API prior to calling Verify. example: '123457' customer_account_token: type: string minLength: 1 maxLength: 255 nullable: true description: > Alternative to raw account data when the account was previously tokenized. If provided, raw account fields (`account`, `expiration_date`, `recipient_first_name`, `recipient_last_name`, `recipient_address1`, `recipient_city`, `recipient_state`, `recipient_zip`) are not required and should be omitted. example: ca875cce-58c0-46a0-8f14-676190cc7df6 amount: type: number format: float minimum: 0.01 nullable: true description: > Dollar amount of disbursement. Max value determined by participant velocity limits. example: 101 recipient_first_name: type: string minLength: 1 maxLength: 255 description: > Customer first name. Required unless `customer_account_token` is provided. example: Johnny recipient_last_name: type: string minLength: 1 maxLength: 255 description: > Customer last name. Required unless `customer_account_token` is provided. example: Rockets recipient_business_name: type: string maxLength: 150 nullable: true description: Optional recipient business name. example: null account: type: string minLength: 1 maxLength: 255 description: > Card or bill payment account number. Required unless `customer_account_token` is provided. example: 411111XXXXXXXXXX expiration_date: type: string maxLength: 4 pattern: ^[0-9]{2}(0[1-9]|1[0-2])$ nullable: true description: > Card expiration date in YYMM format. Conditionally required for `CA` based on client configuration (`expiration_date_enabled` flag). Not required for `BP` account type or if `customer_account_token` is provided. example: '2612' cvv: type: string pattern: ^[0-9]{3,4}$ nullable: true description: > CVV value (3–4 digits depending on card type). Conditionally required for `CA` based on client configuration (`cvv_enabled` flag). Never required for `BP` account type or if `customer_account_token` is provided. example: '123' recipient_address1: type: string minLength: 1 maxLength: 255 description: > Customer billing address line 1. Required unless `customer_account_token` is provided. example: 123 Main St. recipient_address2: type: string maxLength: 255 nullable: true description: Customer billing address line 2. example: Apt 3 recipient_city: type: string minLength: 1 maxLength: 255 description: > Customer billing city. Required unless `customer_account_token` is provided. example: Atlanta recipient_state: type: string minLength: 2 maxLength: 2 pattern: >- ^(?:A[LKSZRAEP]|C[AOT]|D[EC]|F[LM]|G[AU]|HI|I[ADLN]|K[SY]|LA|M[ADEHINOPST]|N[CDEHJMVY]|O[HKR]|P[ARW]|RI|S[CD]|T[NX]|UT|V[AIT]|W[AIVY])$ description: > Customer billing state (standard US postal abbreviation). Required unless `customer_account_token` is provided. example: GA recipient_zip: type: string maxLength: 10 pattern: ^[0-9]{5}(?:-[0-9]{4})?$ nullable: true description: > Customer billing zip code. 5-digit zip or zip+4 in xxxxx-xxxx format. Required unless `customer_account_token` is provided. example: '30313' recipient_phone: type: string maxLength: 10 nullable: true description: 10-digit recipient phone number. example: '1231231234' store_id: type: string minLength: 1 maxLength: 255 description: > Client assigned store ID. Required when the client is configured as a retail participant (`retail` flag enabled in client configuration). example: STORE-001 terminal_id: type: string minLength: 1 maxLength: 255 description: > Client assigned terminal ID. Required when the client is configured as a retail participant (`retail` flag enabled in client configuration). example: TERM-042 clerk_id: type: string minLength: 1 maxLength: 255 description: > Client assigned clerk ID. Required when the client is configured as a retail participant (`retail` flag enabled in client configuration). example: CLK-007 participant_unique_id1: type: string minLength: 1 maxLength: 255 description: > Participant assigned ID to be associated with `customer_account_token` creation. Should correlate to participant assigned values affiliated with future process requests for tracking purposes. Must not contain NPI data. example: fb746578-c4c3-498f-b398-1ff07b4fe2ff participant_unique_id2: type: string maxLength: 255 nullable: true description: > Optional second participant assigned ID. Should be carried forward to future process requests for tracking purposes. Must not contain NPI data. example: 77d6b010-eab4-44dc-9a27-6ffa4838c9f2 timestamp: type: integer format: int64 description: Unix timestamp of the request. example: 1579832224 version: type: integer description: API version of the request. Current version is 11. example: 11 VerifyRetailCardPresentResponse: type: object properties: status: type: integer description: > Numeric code describing the status of the API request. 100 = Success. example: 100 client_message: type: string description: Text description associated with the status code. example: Success data: type: object properties: customer_account_token: type: string description: > GUID — unique value generated based upon account and recipient data. Use this token in all subsequent Process requests for this account. example: 715b9903-7bcd-45ae-bc92-4092c8186d9f last_4: type: string description: The last 4 digits of the account number. example: '1111' request_timestamp: type: integer format: int64 description: Unix timestamp of the request. example: 1579832224 issuers: type: array description: Information about the issuer of the card or biller. items: type: object properties: payee_id: type: string description: The Ingo assigned ID for the payee. example: '526263' payee_name: type: string description: Name of payee (biller/issuer). example: Bank of America - Platinum MasterCard and Visa payee_address: type: string nullable: true description: Payee address. example: PO Box 15019 payee_city: type: string nullable: true description: Payee city. example: Wilmington payee_state: type: string nullable: true description: Payee state. example: DE payee_zip: type: string nullable: true description: Payee zip code. example: 19850-5019 credit_info: type: object nullable: true description: > Information regarding limits for push (credit) transactions. Returned if participant is enabled for push and account is enabled for push processing. properties: min: type: string description: Minimum amount accepted for a push transaction. example: '0.05' max: type: string description: Maximum amount accepted for a push transaction. example: '1500.00' card_type: type: string description: The type of card (e.g. Debit, Prepaid). example: Debit estimated_posting_time: type: string description: Estimated posting time narrative. example: Payment will post Next Business Day estimated_posting_date: type: string description: Estimated posting date. example: 04/22/2026 debit_info: type: object nullable: true description: > Information regarding limits for pull (debit) transactions. Returned if participant is enabled for pull and account is enabled for pull processing. properties: min: type: string description: Minimum amount accepted for a pull transaction. example: '0.05' max: type: string description: Maximum amount accepted for a pull transaction. example: '1500.00' card_type: type: string description: The type of card. example: Debit issuing_network: type: string description: Information regarding the issuing network of the card. example: Visa credit_enabled: type: integer enum: - 0 - 1 description: > Whether the account is enabled for push (credit) transactions. 1 = Enabled, 0 = Not enabled. example: 1 debit_enabled: type: integer enum: - 0 - 1 description: > Whether the account is enabled for pull (debit) transactions. 1 = Enabled, 0 = Not enabled. example: 0 participant_unique_id1: type: string description: Echo of participant assigned ID for the verify request. example: fb746578-c4c3-498f-b398-1ff07b4fe2ff participant_unique_id2: type: string nullable: true description: > Echo of optional second participant assigned ID for the verify request. example: 77d6b010-eab4-44dc-9a27-6ffa4838c9f2 expiration_date: type: string nullable: true description: > Expiration date of the card associated with the `customer_account_token` in YYMM format. Returned for `CA` account type only. example: '2612' count: type: integer description: Always returns 1. example: 1 time: type: string description: Time in seconds to complete the request. example: '4.0146' ErrorResponse: type: object properties: status: type: integer example: 700 client_message: type: string example: Account not currently available for payment data: type: object properties: request_timestamp: type: integer format: int64 example: 1579832224 securitySchemes: HmacAuth: type: apiKey in: header name: Authorization description: >- HMAC-SHA512 signed Authorization header. See the Authentication page for the complete signing guide. security: - HmacAuth: []