Exirom Payment API Documentation

POST /api/v1/payouts/apm/kyc/{transactionId}

Submits the customer's identity data for a payout that requires KYC. The required data varies by payout method — the example below carries the data PayID asks for.

Guide: APM Identity Verification — conceptual walkthrough, flow diagrams, and integration patterns.

#Headers

Header	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer {token}` — see Authentication

#Path Parameters

Parameter	Type	Required	Description
`transactionId`	integer	Yes	transactionId of the payout that returned KYC_REQUIRED.

#Request Body Parameters

Field	Type	Required	Description
`kycData`	Object — See KycData	Yes	Customer identity data for any payment method that asks for verification. Fields are optional in the schema; the payment method decides which are required, and missing or unsupported ones are returned in kycResponseData.errors. The payment method's guide lists its required data.

Field	Type	Required	Description
`person`	Object — See KycPerson	No
`address`	Object — See KycAddress	No
`documents`	Array<KycDocument>	No	Identity documents.
`additionalFields`	Map<String, String>	No	Extra fields, only for payment methods whose guide lists them.

Field	Type	Required	Description
`firstName`	String	No	Legal first name.
`lastName`	String	No	Legal last name.
`dateOfBirth`	String	No	Date of birth, YYYY-MM-DD.
`middleName`	String	No	Middle name, for payment methods that use it.
`nationality`	String	No	ISO 3166-1 alpha-2 nationality code, for payment methods that use it.
`gender`	String (MALE, FEMALE, OTHER)	No	Gender, for payment methods that use it.

Field	Type	Required	Description
`line1`	String	No	Residential address line 1.
`line2`	String	No	Residential address line 2, if applicable.
`city`	String	No	Residential city.
`state`	String	No	Residential state or region, if applicable.
`postcode`	String	No	Residential postal code.
`country`	String	No	Residential country, ISO 3166-1 alpha-2 code.

Field	Type	Required	Description
`type`	String (PASSPORT, DRIVING_LICENCE, NATIONAL_ID, OTHER)	No	Document type. OTHER with customType only for payment methods whose guide lists it.
`country`	String	No	Issuing country, ISO 3166-1 alpha-2 code.
`number`	String	No	Document number.
`images`	Array<KycImage>	No	Images of this document, identified by side rather than array position.
`customType`	String	No	Document kind when type is OTHER.

Field	Type	Required	Description
`side`	String (FRONT, BACK, SELFIE, OTHER)	No	Image role within the document.
`contentType`	String	No	Media type of the image, for example image/jpeg.
`data`	String	No	Base64 image without a data-URL prefix. The payment method's guide lists accepted formats and sizes; the whole request must not exceed 16 MiB.

#Response

Field	Type	Description
`requestId`	String	The requestId of the original payment or payout. Not an input or retry key for this KYC endpoint.
`transactionId`	String	Unique transaction identifier assigned by Exirom. Use this ID to query status, retrieve info, or reference the transaction in support requests.
`transactionStatus`	String (NEW, PENDING, FAILED, REFUNDED, CUSTOMER_VERIFICATION, ...)	CUSTOMER_VERIFICATION while kycResponseData.errors must be corrected; otherwise the status of the continued transaction, as in the payment method's usual response, or FAILED.
`declineCode`	Integer	Decline code of a FAILED transaction. 4034, 4035 and 4036 are verification declines; other decline codes are possible when the continued transaction is declined.
`apmResponseData`	Object — See ApmResponseData	Payment method-specific response data. Structure varies by APM type. May include redirect URLs, QR codes, or provider references.
`kycResponseData`	Object — See KycResponseData	Present only when the submitted data was not accepted. apmResponseData is then absent.
`paymentType`	String (APM)	Payment type identifier: `CARD` for card transactions, `APM` for alternative payment methods.

Field	Type	Description
`providerTransactionId`	String	Transaction identifier from the upstream payment service provider.
`iframeUrl`	String	Page to embed in an iframe. With actionType KYC_REQUIRED it is the identity verification form: add the parentOrigin query parameter and relay its messages as described in the KYC Widget Integration guide. With REDIRECTION some providers also return an embeddable version of redirectUrl.
`actionType`	String (REDIRECTION, QR, NONE, REFERENCE, KYC_REQUIRED)
`qrData`	String
`qrDeepLink`	String
`qrValue`	String
`references`	Array<ApmResponseReference>
`customerInstructionsByLanguage`	Map<String, String>	Markdown payment instructions keyed by language code. Use the selected language, falling back to en, then an available translation. No instructions are displayed when the map is absent or empty.
`redirectUrl`	String	Full-page redirect URL where the customer completes payment. Use this for standard redirect flow.
`paymentType`	String (BANK_TRANSFER, CARD_PAYMENT, E_WALLET, MOBILE_WALLET, CASH, ...)	Payment type identifier: `CARD` for card transactions, `APM` for alternative payment methods.
`paymentMethod`	String (PAYPAL, IDEAL, GOOGLE_PAY, APPLE_PAY, EXTERNAL_HPP_GOOGLE_PAY, ...)	APM method identifier (e.g. `SMART_BANK_TRANSFER`, `PIX_QR`). See apmPayload References.

Field	Type	Description
`errors`	Array<KycValidationError>	Every error found in the submission. Show each at its field, or at form level when field is null.

Field	Type	Description
`key`	String
`label`	String
`value`	String

Field	Type	Description
`code`	String (KYC_INVALID_FIELD, KYC_INVALID_IMAGE, KYC_IMAGE_TOO_LARGE, KYC_VALIDATION_FAILED)	An error with field set to null applies to the submission as a whole rather than to one field.
`field`	String	Path relative to kycData with zero-based indices, for example person.dateOfBirth; null for a form-level error.
`messagesByLanguage`	Map<String, String>	Customer-facing messages keyed by lowercase ISO 639-1 language code: en, es, pt. Submitted values are never echoed.

{
  "kycData": {
    "person": {
      "firstName": "Alex",
      "lastName": "Example",
      "dateOfBirth": "1990-05-01",
      "gender": "FEMALE"
    },
    "address": {
      "line1": "1 Example Street",
      "city": "Sydney",
      "state": "NSW",
      "postcode": "2000",
      "country": "AU"
    },
    "documents": [
      {
        "type": "DRIVING_LICENCE",
        "country": "AU",
        "number": "EXAMPLE123",
        "images": [
          {
            "side": "FRONT",
            "contentType": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jD1cAAAAASUVORK5CYII="
          },
          {
            "side": "BACK",
            "contentType": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jD1cAAAAASUVORK5CYII="
          }
        ]
      }
    ]
  }
}

{
  "requestId": "original-payout-request",
  "transactionId": "123456790",
  "transactionStatus": "PENDING",
  "paymentType": "APM",
  "apmResponseData": {
    "paymentMethod": "PAY_ID",
    "paymentType": "BANK_TRANSFER",
    "actionType": "NONE",
    "providerTransactionId": "payout-1"
  }
}

Idempotency: After an unconfirmed response (503 or 504), retry the same transaction with the same KYC data. After input errors, submit the corrected data for the same transaction. This endpoint accepts no requestId; never create a new transaction automatically.

#Error Responses

HTTP Status	Description
`400`	Malformed request, for example kycData is missing. Fix the request; the transaction is unchanged.
`401`	Merchant authentication required.
`403`	Missing payment-write permission, or the payout belongs to another merchant.
`404`	No payout with this transactionId; a payment transactionId also returns 404 here.
`413`	Request body larger than 16 MiB, or sent without Content-Length. Send fewer or smaller images; the transaction is unchanged.
`422`	The payout is not waiting for KYC: its action is not KYC_REQUIRED or it already has a result. Do not resubmit; read the payout status instead.
`503`	Result unconfirmed: verification could not be reached, or the platform returned an unexpected error. The payout is not declined by this response. Retry the same transaction with the same data a bounded number of times, then read the transaction status instead of retrying further.
`504`	Result unconfirmed: verification did not finish in time. Retry the same transaction with the same data. If the payout has meanwhile received a result, the retry returns 422 and the status endpoint shows it.
`429`	Too Many Requests — rate limit exceeded. Back off before retrying.
`500`	Internal Server Error — an unexpected error occurred. Retry with exponential backoff.

curl -X POST https://sandbox.api.exirom.com/api/v1/payouts/apm/kyc/12345 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
  "kycData": {
    "person": {
      "firstName": "Alex",
      "lastName": "Example",
      "dateOfBirth": "1990-05-01",
      "gender": "FEMALE"
    },
    "address": {
      "line1": "1 Example Street",
      "city": "Sydney",
      "state": "NSW",
      "postcode": "2000",
      "country": "AU"
    },
    "documents": [
      {
        "type": "DRIVING_LICENCE",
        "country": "AU",
        "number": "EXAMPLE123",
        "images": [
          {
            "side": "FRONT",
            "contentType": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jD1cAAAAASUVORK5CYII="
          },
          {
            "side": "BACK",
            "contentType": "image/png",
            "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jD1cAAAAASUVORK5CYII="
          }
        ]
      }
    ]
  }
}'

#Try It

SandboxTry it

https://sandbox.api.exirom.com/api·Production URL: contact your account manager

Auth Token

Path Params

transactionId=

Request Body