Exirom Payment API Documentation

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

Submits the customer's identity data for a payment that requires KYC. The required data varies by payment 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 payment 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-payment-request",
  "transactionId": "123456789",
  "transactionStatus": "PROCESSING",
  "paymentType": "APM",
  "apmResponseData": {
    "paymentMethod": "PAY_ID",
    "paymentType": "BANK_TRANSFER",
    "actionType": "REFERENCE",
    "providerTransactionId": "payment-1",
    "references": [
      {
        "key": "bankName",
        "label": "Bank",
        "value": "Example Bank"
      },
      {
        "key": "accountHolder",
        "label": "Account holder",
        "value": "Example Holder"
      },
      {
        "key": "accountNumber",
        "label": "Account number",
        "value": "00123456"
      },
      {
        "key": "payidReference",
        "label": "Payment reference",
        "value": "A4K9PX"
      }
    ],
    "customerInstructionsByLanguage": {
      "en": "## How to pay\n\n1. Open your banking app and create a new transfer to the account shown.\n2. Enter the displayed amount in AUD.\n3. Enter the payment reference exactly as shown in the transfer description.\n4. Confirm the transfer.\n\nYou will be redirected back to the merchant as soon as we receive your payment."
    }
  }
}

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 payment belongs to another merchant.
`404`	No payment with this transactionId; a payout 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 payment is not waiting for KYC: its action is not KYC_REQUIRED or it already has a result. Do not resubmit; read the payment status instead.
`503`	Result unconfirmed: verification could not be reached, or the platform returned an unexpected error. The payment 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 payment 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/payments/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