Interchecks Recipient Verification API

openapi: 3.2.0
info:
  title: Payments API V2 Recipient Verification API
  description: "# Introduction\nPayments API v2 enables payers to:\n- Create and manage recipients at an aggregator or payer level\n- Create and manage destination payment accounts at an aggregator or payer level\n- Create and manage payments for Portal acceptance\n- Create payout transactions for immediate disbursement\n\n# Idempotent Requests\nThe API supports **Idempotency** for safely retrying requests without performing the same operation twice for **Create Payment** and **Create Transaction** endpoints.  Add the `Idempotency-Key: <key>` header to the request using a unique value as the key.  Idempotency Keys are honored for 24 hours and only for **20x** and **400** responses.  If the supplied ~Idempotency-Key` value matches an existing request the following HTTP Status codes may be returned.\n- **102 PROCESSING** : We are still processing the request\n- **409 CONFLICT** : We have previously processing the request and return the original response body payload.\n\n# HTTP Status Codes\n| HTTP Status Code | Description |\n| --- | ---- |\n| 102 | Idempotent request is current processing |\n| 200 | Request processed |\n| 201 | Request processed and entity created |\n| 400 | Bad request due to invalid or missing parameters |\n| 401 | Not Authenticated |\n| 403 | Not Authorized |\n| 404 | Resource or entity not found |\n| 409 | Idempotent request conflict |\n| 429 | Too many requests in a given amount of time |\n| 500 | Unexpected error while processing the request |\n| 503 | Service unavailable or timeout |\n\n# Error Response\nRequests resulting in an error response will contain an HTTP status code, error message, and an error code for non-authentication related errors.\n\n** Authentication Error example **\n```\n{\n    \"http_status\": 401,\n    \"error_message\": \"401 UNAUTHORIZED\"\n}\n```\n### Authorization Error example\n```\n{\n    \"http_status\": 403,\n    \"error_message\": \"403 FORBIDDEN\"\n}\n```\n### Bad Request example\n```\n{\n    \"http_status\": 400,\n    \"error_code\": \"ERR_INVALID_RECIPIENT_ID\",\n    \"error_message\": \"Invalid recipient ID\"\n}\n```\n\n# Error Codes\nListed in alphabetical order\n\n| Error Code | Error Message |\n| --- | --- |\n| ERR_ACCOUNT_LIMIT_EXCEEDED | Activity limit exceeded |\n| ERR_ACCOUNT_PROVIDER_NOT_ENABLED | Payer not enabled for Account Provider |\n| ERR_ACCOUNT_PROVIDER_MISMATCH | Account invalid for provider |\n| ERR_CARD_INELIGIBLE | Card ineligible |\n| ERR_CLIENT_ACCESS_PAYER | Client does not have access to payer |\n| ERR_CREDIT_CARD_NOT_SUPPORTED | Credit cards not supported |\n| ERR_EMAIL_IN_USE | Recipient email is assigned to another profile |\n| ERR_INTERNAL_SERVER_ERROR | Internal server error |\n| ERR_INVALID_ACCOUNT_ID | Invalid account ID |\n| ERR_INVALID_CARD_DETAILS | Invalid card details |\n| ERR_INVALID_COUNTRY | Invalid Country |\n| ERR_INVALID_CURRENCY_CODE | Invalid Currency Code |\n| ERR_INVALID_EMAIL | Invalid email |\n| ERR_INVALID_NAME | Invalid or missing name fields |\n| ERR_INVALID_PARAMETER | Missing or invalid request parameters |\n| ERR_INVALID_PAYMENT_ID | Invalid payment ID |\n| ERR_INVALID_PAYER_ID | Invalid payer ID |\n| ERR_INVALID_PAYMENT_REFERENCE_ID | Payment reference ID not found |\n| ERR_INVALID_PAYOUT_METHOD_FOR_ACCOUNT | Invalid payout method for account |\n| ERR_INVALID_RECIPIENT_EMAIL | Invalid recipient email |\n| ERR_INVALID_RECIPIENT_ID | Invalid recipient ID |\n| ERR_INVALID_RECIPIENT_REFERENCE_ID | Recipient reference ID not found |\n| ERR_INVALID_ROUTING_NUMBER | Invalid Routing Number |\n| ERR_INVALID_STATE | Invalid State |\n| ERR_INVALID_TRANSACTION_ID | Invalid transaction ID |\n| ERR_INVALID_TRANSACTION_REFERENCE_ID | Transaction reference ID not found |\n| ERR_MISSING_RECIPIENT | Missing recipient ID or email |\n| ERR_OCT_DECLINE | (Error specific to decline reason) | \n| ERR_OFAC_LIST_MATCH | Cancelled due to OFAC list match |\n| ERR_PAYMENT_STATUS_IMMUTABLE | Payment in immutable status |\n| ERR_PAYMENT_STATUS_NOT_APPLICABLE | Payment status cannot be applied |\n| ERR_PAYOUT_METHOD_NOT_AVAILABLE | Payout method not available |\n| ERR_RECIPIENT_NOT_FOUND | Recipient email not found |\n| ERR_RETRIEVING_CARD_DETAILS | Error determining card eligibility |\n| ERR_TRANSACTION_FAILURE | (Error specific to transaction failure) |\n| ERR_VERIFICATION_NOT_ENABLED | Payer not enabled for TIN Verification |"
  contact: {}
  version: '2'
servers:
- url: http://example.com
  variables: {}
security:
- httpBearer: []
tags:
- name: Recipient Verification
paths:
  /api/v2/{payer_id}/recipients/{recipient_id}/verification:
    post:
      tags:
      - Recipient Verification
      summary: Verify Recipient TIN
      operationId: VerifyRecipientTIN
      parameters:
      - name: payer_id
        in: path
        description: ''
        required: true
        style: simple
        schema:
          type: string
      - name: recipient_id
        in: path
        description: ''
        required: true
        style: simple
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyRecipientTINRequest'
            example:
              tin: '123456789'
              address:
                address_1: 134 N 4th St
                city: Brooklyn
                state: NY
                zip: '11249'
              legal_entity_type: INDIVIDUAL
        required: true
      responses:
        '200':
          description: ''
          headers: {}
      deprecated: false
    get:
      tags:
      - Recipient Verification
      summary: Get Recipient TIN Verification
      operationId: GetRecipientTINVerification
      parameters:
      - name: payer_id
        in: path
        description: ''
        required: true
        style: simple
        schema:
          type: string
      - name: recipient_id
        in: path
        description: ''
        required: true
        style: simple
        schema:
          type: string
      responses:
        '200':
          description: ''
          headers: {}
      deprecated: false
components:
  schemas:
    Address:
      title: Address
      required:
      - address_1
      - city
      - state
      - zip
      type: object
      properties:
        address_1:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
      example:
        address_1: 134 N 4th St
        city: Brooklyn
        state: NY
        zip: '11249'
    VerifyRecipientTINRequest:
      title: VerifyRecipientTINRequest
      required:
      - tin
      - address
      - legal_entity_type
      type: object
      properties:
        tin:
          type: string
        address:
          $ref: '#/components/schemas/Address'
        legal_entity_type:
          type: string
      example:
        tin: '123456789'
        address:
          address_1: 134 N 4th St
          city: Brooklyn
          state: NY
          zip: '11249'
        legal_entity_type: INDIVIDUAL
  securitySchemes:
    httpBearer:
      type: http
      scheme: bearer