IRT

Register a sender

Changed on Nov 3, 2026

Registers a sender, or updates the one already registered under the same externalId — the pair (merchant, externalId) is unique per mode, so replaying a registration never creates a duplicate. The sender is screened against the sanctions lists on every call that can change it. If the screening cannot run, a new sender or a changed identity is held pending with reason screening_incomplete, an unchanged one keeps its state, and a rejected sender is returned unchanged — send it again once screening is back. A sender rejected by Hub2 compliance is returned unchanged, and a disabled sender cannot be registered again (422 sender_disabled).

post/irt/v1/senders

Request

The document declares no server URL.
Auth
none declared. Required headers: ApiKey, MerchantId, Environment

Headers

ApiKeystring required

Your api key. To create a key, please get into our dashboard. If you don't have access to it, please reach the Support team.

MerchantIdstring required

Your merchant ID. This information is available in our dashboard. If you don't have access to it, please reach the Support team.

Environment'live' | 'sandbox' required

Allow you to choose between the sandbox mode to perform some tests or the live mode for real world transactions.

Request body

payoutType'individual' | 'business'

Type of sender. Defaults to individual when omitted, preserving the existing C2C behaviour. Set to business to send business sender fields instead of individual ones.

firstNamestring

First name of the sender (individual senders only)

lastNamestring

Last name of the sender (individual senders only)

contactPhonestring

Contact phone number of the sender (individual senders only)

dateOfBirthstring

Date of birth of the sender in YYYY-MM-DD format (individual senders only)

nationality'AF' | 'AX' | 'AL' | 'DZ' | 'AS' | 'AD' | 'AO' | 'AI' | 'AQ' | 'AG' | 'AR' | 'AM' | 'AW' | 'AU' | 'AT' | 'AZ' | 'BS' | 'BH' | 'BD' | 'BB' | 'BY' | 'BE' | 'BZ' | 'BJ' | 'BM' | 'BT' | 'BO' | 'BQ' | 'BA' | 'BW' | 'BV' | 'BR' | 'IO' | 'BN' | 'BG' | 'BF' | 'BI' | 'KH' | 'CM' | 'CA' | 'CV' | 'KY' | 'CF' | 'TD' | 'CL' | 'CN' | 'CX' | 'CC' | 'CO' | 'KM' | 'CG' | 'CD' | 'CK' | 'CR' | 'CI' | 'HR' | 'CU' | 'CW' | 'CY' | 'CZ' | 'DK' | 'DJ' | 'DM' | 'DO' | 'EC' | 'EG' | 'SV' | 'GQ' | 'ER' | 'EE' | 'ET' | 'FK' | 'FO' | 'FJ' | 'FI' | 'FR' | 'GF' | 'PF' | 'TF' | 'GA' | 'GM' | 'GE' | 'DE' | 'GH' | 'GI' | 'GR' | 'GL' | 'GD' | 'GP' | 'GU' | 'GT' | 'GG' | 'GN' | 'GW' | 'GY' | 'HT' | 'HM' | 'VA' | 'HN' | 'HK' | 'HU' | 'IS' | 'IN' | 'ID' | 'IR' | 'IQ' | 'IE' | 'IM' | 'IL' | 'IT' | 'JM' | 'JP' | 'JE' | 'JO' | 'KZ' | 'KE' | 'KI' | 'KR' | 'KP' | 'KW' | 'KG' | 'LA' | 'LV' | 'LB' | 'LS' | 'LR' | 'LY' | 'LI' | 'LT' | 'LU' | 'MO' | 'MK' | 'MG' | 'MW' | 'MY' | 'MV' | 'ML' | 'MT' | 'MH' | 'MQ' | 'MR' | 'MU' | 'YT' | 'MX' | 'FM' | 'MD' | 'MC' | 'MN' | 'ME' | 'MS' | 'MA' | 'MZ' | 'MM' | 'NA' | 'NR' | 'NP' | 'NL' | 'NC' | 'NZ' | 'NI' | 'NE' | 'NG' | 'NU' | 'NF' | 'MP' | 'NO' | 'OM' | 'PK' | 'PW' | 'PS' | 'PA' | 'PG' | 'PY' | 'PE' | 'PH' | 'PN' | 'PL' | 'PT' | 'PR' | 'QA' | 'RE' | 'RO' | 'RU' | 'RW' | 'BL' | 'SH' | 'KN' | 'LC' | 'MF' | 'PM' | 'VC' | 'WS' | 'SM' | 'ST' | 'SA' | 'SN' | 'RS' | 'SC' | 'SL' | 'SG' | 'SX' | 'SK' | 'SI' | 'SB' | 'SO' | 'ZA' | 'GS' | 'SS' | 'ES' | 'LK' | 'SD' | 'SR' | 'SJ' | 'SZ' | 'SE' | 'CH' | 'SY' | 'TW' | 'TJ' | 'TZ' | 'TH' | 'TL' | 'TG' | 'TK' | 'TO' | 'TT' | 'TN' | 'TR' | 'TM' | 'TC' | 'TV' | 'UG' | 'UA' | 'AE' | 'GB' | 'US' | 'UM' | 'UY' | 'UZ' | 'VU' | 'VE' | 'VN' | 'VG' | 'VI' | 'WF' | 'EH' | 'YE' | 'ZM' | 'ZW'

Nationality of the sender (individual senders only)

namestring

Registered legal name of the business sender (business senders only)

countryOfIncorporationstring

Country of incorporation as an ISO 3166-1 alpha-2 code (business senders only)

Legal entity type of the business sender (business senders only)

registrationDatestring

Business registration date in YYYY-MM-DD format, must be in the past (business senders only)

registrationNumberstring

Business registration number (business senders only)

tradingCountrystring

Trading address country as an ISO 3166-1 alpha-2 code (business senders only)

tradingCitystring

Trading address city (business senders only)

tradingStreetstring

Trading address street (business senders only)

tradingPostalCodestring

Trading address postal code (business senders only)

Primary business activity of the sender (business senders only)

phoneNumberstring

Business contact phone number in E.164 format (business senders only)

emailstring

Business contact email address (business senders only)

externalIdstring required

Your own identifier for this sender. Unique per merchant and per mode: calling this endpoint again with the same value updates the existing sender instead of creating a duplicate.

Example request

{
  "payoutType": "individual",
  "firstName": "Aminata",
  "lastName": "Traoré",
  "contactPhone": "+2250747123456",
  "dateOfBirth": "1992-05-23",
  "nationality": "CI",
  "idDocument": {
    "expiryDate": "2025-12-31",
    "idNumber": "123456789",
    "idType": "passport",
    "issueDate": "2020-01-01",
    "issuer": "Ministry of Interior",
    "issuerCountry": "CI",
    "issuerPlace": "Abidjan",
    "otherIdDescription": "Custom identification document"
  },
  "name": "TikTok Inc.",
  "countryOfIncorporation": "US",
  "legalEntityType": "privately_owned_company",
  "registrationDate": "2012-01-25",
  "registrationNumber": "VAT1234567",
  "tradingCountry": "US",
  "tradingCity": "New York",
  "tradingStreet": "20 W 34th St",
  "tradingPostalCode": "10001",
  "natureOfBusiness": "retail_trade",
  "phoneNumber": "+15555551234",
  "email": "tiktok@payments.com",
  "externalId": "MTO-SENDER-00123"
}

Response

idstring required

Hub2 identifier of the sender. Use it to reference the sender on a transaction.

externalIdstring required

Your own identifier for this sender, as supplied on creation.

payoutType'individual' | 'business' required

Type of sender identity carried by this record.

state'pending' | 'approved' | 'rejected' | 'disabled' required

Lifecycle state of the sender. Only approved senders may be used to initiate a transaction. pending senders await a Hub2 compliance review, rejected and disabled ones cannot transact.

stateReason'possible_match' | 'screening_incomplete' | 'kyc_incomplete' | 'sanctions_match' | 'compliance_block' nullable required

Why the sender is pending (possible_match, screening_incomplete, kyc_incomplete) or rejected (sanctions_match, compliance_block); null for approved and disabled senders. Hub2's decision, distinct from screening.reason, which is what the sanctions screening matched.

screeningobject

Outcome of the last sanctions screening of the current identity. Absent while none has completed on it — a sender pending with reason screening_incomplete.

createdAtstring required

Creation date of the sender, in ISO 8601 format.

updatedAtstring required

Date of the last update of the sender, in ISO 8601 format.

Example response

{
  "id": "snd_V1StGXR8Z5jdHi6BmyT",
  "externalId": "MTO-SENDER-00123",
  "payoutType": "individual",
  "state": "approved",
  "kyc": {
    "payoutType": "individual",
    "firstName": "Aminata",
    "lastName": "Traoré",
    "contactPhone": "+2250747123456",
    "dateOfBirth": "1992-05-23",
    "nationality": "CI",
    "idDocument": {
      "expiryDate": "2025-12-31",
      "idNumber": "123456789",
      "idType": "passport",
      "issueDate": "2020-01-01",
      "issuer": "Ministry of Interior",
      "issuerCountry": "CI",
      "issuerPlace": "Abidjan",
      "otherIdDescription": "Custom identification document"
    },
    "name": "TikTok Inc.",
    "countryOfIncorporation": "US",
    "legalEntityType": "privately_owned_company",
    "registrationDate": "2012-01-25",
    "registrationNumber": "VAT1234567",
    "tradingCountry": "US",
    "tradingCity": "New York",
    "tradingStreet": "20 W 34th St",
    "tradingPostalCode": "10001",
    "natureOfBusiness": "retail_trade",
    "phoneNumber": "+15555551234",
    "email": "tiktok@payments.com"
  },
  "screening": {
    "decision": "ALLOW",
    "reason": "NO_MATCH",
    "screenedAt": "2026-08-07T09:15:00.000Z"
  },
  "createdAt": "2026-08-07T09:15:00.000Z",
  "updatedAt": "2026-08-07T09:15:00.000Z"
}

Changes

Nov 3, 2026f6d3f87df5e0 Revision changes
- info
  endpoint added

Operation history