Skip to main content

Create Payment v2

API to push payment instructions into the NIUM platform. This section is used to elaborate upon some of the capabilities within the API:

URL
POST https://api-test.instarem.com:4803/api/v2/payouts

Header Parameters​

ParameterDescriptionTypeRequired
authorizationAuthentication tokenStringYes
content-typeThe Content-Type entity header is used to indicate the media type of the resource. Expected value is application/json.StringYes
X-CLIENT-IDUnique id for client generated by Nium, Required only in case of partner based model (E.g. 593feb7c7c52bb2357b2df6c).StringNo

Example Request​

curl --location --request POST 'https://api-test.instarem.com:4803/api/v2/payouts' \\
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM' \\
--header 'Content-Type: application/json' \\
--data-raw '{
"request_id": "1XkQkI34DA",
"transaction_number": "ZQ1101",
"destination_account": 1024501739830,
"destination_currency": "USD",
"local_conversion_currency": "USD",
"statement_narrative": "Salary",
"original_remitter_fi": "",
"source_account": 101950173983,
"source_amount": 1000,
"beneficiary": {
"name": "Mark Jobs",
"address": "New york city USA",
"city": "New York",
"country_code": "US",
"email": "example@mail.com",
"account_type": "Individual",
"contact_number": "1234567891",
"state": "New York",
"postcode": "10005",
"wallet_id": "64000000003",
"account_number": "12342346545123",
"bank_account_type": "Checking",
"bank_name": "Bank of America",
"bank_code": "545343545345354",
"identification_type": "Company Organization Code",
"identification_value": "12345678-X",
"card_number": "1234123412341234",
"encrypted_card_number": "bjQdreWkCvrO6lBzKqheGVZI3n_H5Cy9lMbkAepwIGlsfesJ7eHy4GVzWoDefDBdQvFtWVhNrbyHFf0hA5_FI5eYIcuCuapMcOpf6U527xpEyQh2HfOEqegQF4yFG83P56T1u7AHATM+VJdLcBZWfPQtEegG8fAiBpZa3Zy3YA37wrNhY2JDPlwj6LyWN2kkgh_PxLcLL4dWKrSw7spSnOrJLQO5pxb6X+OTmIwS+mWCBJCRMQxq2y5KmvMiv+HqR1Omw+2DYXBfyCgpFiZ9PzoS+JkGXvcMKwZ5hPjEj27IdU4somaVj45GykyI956xft+vN6OhqCrP82Yylhziiw=="
"card_expiry_date": "2020-12",
"relationship": "Employee",
"account_identifier_type": "MOBILE",
"account_identifier_value": "+919021221212",
"card_token": "f758a897-80e3-4d81-ba4d-baf860f8c2a8",
"contact_country_code": "+1",
"name_local_language": "マーク ジョブス",
"ultimate_beneficiary_name": "Joseph Jobs"
},
"remitter": {
"name": "Instarem",
"given_name": true,
"account_type": "Company",
"bank_account_number": "10022206393",
"identification_type": "Company Registration No",
"identification_number": "IN1244654",
"country_code": "IN",
"address": "Sakinaka Mumbai India",
"purpose_code": "IR001",
"source_of_income": "Cross border remittence",
"contact_number": "1234567890",
"dob": "1980-01-01",
"city": "Mumbai",
"postcode": "4703101",
"state": "Maharashtra",
"source_of_funds": "",
"place_of_birth": "IN",
"nationality": "IN",
"occupation": "EXECUTIVE"
},
"originating_parties": [
{
"role": "originating_institution",
"sequence": 1,
"bic": "BOFAUS5N",
"lei": "549311ZZZZZZ",
"name": "matchedTerms trust",
"country": "SG"
},
{
"role": "originating_institution",
"sequence": 2,
"bic": "BOFAUS5N",
"lei": "549311ZZZZZZ",
"name": "Bank thane",
"country": "US"
}
],
"payout_options": {
"fx_hold_id": "5aa22016-10da-11ea-9a9f-362b9e155667"
},
"additional_info": {
"trade_order_id": "",
"trade_time": "",
"trade_currency": "",
"trade_amount": "",
"trade_name": "",
"trade_count": "",
"goods_carrier": "",
"service_detail": "",
"service_time": "",
"cash_pickup": "",
"trade_platform_name": "e-commerce"
},
"routing_code_type_1": "SWIFT",
"routing_code_value_1": "WSD12345",
"routing_code_type_2": "ACH CODE",
"routing_code_value_2": "222333123",
"routing_code_type_3": "",
"routing_code_value_3": "",
"payout_method": "CASH_PAYOUT",
"swift_fee_payer": "ACO",
"document_reference": "6012a81b11c68700c02ef11b",
"beneficiary_intermediary_bank_code" : "BARCFB21",
"payout_rail" : ["INTERAC"],
"biller_code" : "123456",
"customer_reference_number" : "1234567890123456"
}'

Body Parameters​

ParameterDescriptionTypeRequired
request_idA unique request ID specified by the client in the request.StringYes
transaction_numberA unique transaction number specified by the client. Duplicate transaction number will be rejected.StringYes
destination_accountDestination account number.NumberNo
destination_currencyDestination currency (3-letter ISO-4217 code).StringNo
local_conversion_currencyBeneficiary's country local currencyStringNo
statement_narrativePayment Narration.StringYes
original_remitter_ fiOriginal remitter fiStringNo
source_accountSource Account NumberNumberYes
source_amountAmount to send. Mutually exclusive with destination_amount.NumberNo
destination_amountAmount to be paid to beneficiary. Mutually exclusive with source_acount.NumberNo
deposit_methodDeposit Method is CASH, BANK, CARD or WALLETStringNo
beneficiary.nameBeneficiary name.StringYes
beneficiary.addressBeneficiary address.StringNo
beneficiary.cityBeneficiary city.StringNo
beneficiary.country_codeBeneficiary country code (2-letter ISO 3166-2 country code).StringYes
beneficiary.emailBeneficiary email.StringNo
beneficiary.account_typeBeneficary account type either Individual or Company.StringNo
beneficiary.contact_numberBeneficiary contact number.StringNo
beneficiary.dobBeneficiary Date of birth (YYYY-MM-DD).StringNo
beneficiary.establishment_dateBeneficiary Establishment Date (YYYY-MM-DD).StringNo
beneficiary.stateBeneficiary state.StringNo
beneficiary.postcodeBeneficiary postcode.StringNo
beneficiary.wallet_idBeneficiary wallet id. (Deprecated, use beneficiary.account_number)StringNo
beneficiary.account_numberBeneficiary account number.StringNo
beneficiary.bank_account_typeBeneficiary Bank Account Type can be one of Checking, Saving or Maestra.StringNo
beneficiary.bank_nameBeneficiary bank name.StringNo
beneficiary.bank_codeBeneficiary bank code.StringNo
beneficiary.identification_typeOne of Company Organization Code, Company Social Credit Code, Passport, Company Registration No., CUIT, CUIL, CPF, CNPJ, RUT, CC, NIT, CE, PASS, DNI, RUC, CI.StringNo
beneficiary.identification_valueValue corresponding to Beneficiary Identification Type.StringNo
beneficiary.card_numberCard number.(Only valid for GeoSwift Card)StringNo
beneficiary.encrypted_card_numberEncrypted Card Number(For Public key to encrypt card number contact customer success team)StringNo
beneficiary.card_expiry_dateCard expiration date in the format YYYY-MM.StringNo
beneficiary.relationshipRemitter beneficiary relationship.StringNo
beneficiary.account_identifier_typeProxy type for this payout are MOBILE, UEN or NRICStringConditional
beneficiary.account_identifier_valueProxy values are dependent on proxy typeStringConditional
beneficiary.card_tokenCard tokenStringNo
beneficiary.contact_country_codeContact country codeStringNo
beneficiary.name_local_languageBeneficiary's name in local language (e.g. Japanese Katakana)StringNo
beneficiary.ultimate_beneficiary_nameThe entity who directly receives the benefit of a transactionStringNo
remitter.nameRemitter name.StringNo
remitter.given_nameIndicates whether the remitters name should allow initials.BooleanNo
remitter.account_typeRemitter account type either Individual or Company.StringNo
remitter.bank_account_numberRemitter Bank Account Number.StringNo
remitter.identification_typeOne of Registration Number, Registration ID, ACRA,Travel agent License number,Company Registration No,License No,ARNU,DRLC,NIDN,CCPT.StringNo
remitter.identification_numberRemitter identification number is the document identifier i.e. IN1244654.StringNo
remitter.country_codeRemitter country code (2-letter ISO 3166-2 country code).StringNo
remitter.addressRemitter address.StringNo
remitter.purpose_codeThe purpose for the payment, i.e. IR001. Use Instarem's data reference for purpose code.StringNo
remitter.source_of_incomeRemitter source of income.StringNo
remitter.contact_numberRemitter contact number.StringNo
remitter.dobRemitter Date of birth (YYYY-MM-DD).StringNo
remitter.cityRemitter city.StringNo
remitter.postcodeRemitter postcode.StringNo
remitter.stateRemitter state.StringNo
remitter.source_of_fundsRemitters source of funds.StringNo
remitter.place_of_birthRemitter place of birth (2-letter ISO 3166-2 country code).StringNo
remitter.nationalityRemitter nationality (2-letter ISO 3166-2 country code).StringNo
remitter.occupationRemitter occupation, i.e.EXECUTIVE. Use Instarem's data reference for remitter occupation.StringNo
originating_parties.roleInstitution role in routing chainStringNo
originating_parties.sequenceRouting order sequenceNumberNo
originating_parties.bicSWIFT BIC codeStringNo
originating_parties.leiLegal Entity IdentifierStringNo
originating_parties.nameInstitution nameStringYes
originating_parties.countryISO 2-letter country codeStringYes
payout_options.fx_hold_idId of the lock & hold fx rate.StringNo
additional_info.trade_order_idTrade order idStringNo
additional_info.trade_timeTrade timeStringNo
additional_info.trade_currencyTrade currencyStringNo
additional_info.trade_ amountTrade amountNumberNo
additional_info.trade_ nameTrade nameStringNo
additional_info.trade_ countTrade countIntegerNo
additional_info.goods_ carrierGoods carrierStringNo
additional_info.service_ detailService detailStringNo
additional_info.service_ timeService timeStringNo
additional_info.cash_ pickupCash pickupStringNo
additional_info.trade_platform_nameTrade platform name for E-commerce payoutStringNo
routing_code_type_1Routing code type 1 (eg SWIFT for all Countries, IFSC for India, SORT CODE for UK, ACH CODE for USA, BRANCH CODE for Brazil and Bangladesh, BSB CODE for Australia, BANK CODE for HongKong).StringNo
routing_code_value_1Routing code value 1 (eg ADCBINBB or ADCBINBB123 for SWIFT, SBIN0000058 for IFSC, 100000 for SORT CODE, 111000025 for ACH CODE, 012515 for BSB CODE, 151 for BANK CODE).StringNo
routing_code_type_2Routing code type 2 (eg SWIFT for all Countries, IFSC for India, SORT CODE for UK, ACH CODE for USA, BRANCH CODE for Brazil and Bangladesh, BSB CODE for Australia, BANK CODE for HongKong).StringNo
routing_code_value_2Routing code value 2 (eg ADCBINBB or ADCBINBB123 for SWIFT, SBIN0000058 for IFSC, 100000 for SORT CODE, 111000025 for ACH CODE, 012515 for BSB CODE, 151 for BANK CODE).StringNo
routing_code_type_3Routing code type 3 (eg SWIFT for all Countries, IFSC for India, SORT CODE for UK, ACH CODE for USA, BRANCH CODE for Brazil and Bangladesh, BSB CODE for Australia, BANK CODE for HongKong).StringNo
routing_code_value_3Routing code value 3 (eg ADCBINBB or ADCBINBB123 for SWIFT, SBIN0000058 for IFSC, 100000 for SORT CODE, 111000025 for ACH CODE, 012515 for BSB CODE, 151 for BANK CODE).StringNo
payout_methodPayout Method either CASH_PAYOUT or BANK or CARD or WALLET or PROXY or SWIFTStringNo
swift_fee_payerThis field defines who (Corporate / Beneficiary) will bear the SWIFT charges for the given transaction. The allowed values are: ACO, SHA & BENStringNo
document_referenceDocument with reference to transactionsStringNo
beneficiary_intermediary_bank_codeSWIFT BIC associated to the Intermediary AgentStringNo
payout_railThis field can be used for selecting the Payout Rail to be used wherever multiple payout rails are available. The allowed values are: USD: ['ACH'], CAD: ['INTERAC', 'EFT']Array<String>No
biller_codeBPAY biller code for bill payments in AustraliaStringNo
customer_reference_numberCustomer reference number for BPAY bill payments in AustraliaStringNo

Example Response​

{
"reference_number": "ZQ1101",
"payment_id": "PY10001485",
"status": "IN_PROCESS",
"sub_status": "",
"status_description": "Payment in internal process",
"created_at": "2017-06-16T17:25:52.136+05:30",
"updated_at": "2017-06-16T17:26:20.670+05:30",
"hold_fx_expires_on": "2017-06-17T17:26:20.670+05:30"
}

Response Parameters​

ParameterDescriptionType
reference_numberTransaction Reference NumberString
payment_idTransaction idString
statusTransaction StatusString
sub_statusTransaction Sub StatusString
status_descriptionTransaction Status detailsString
created_atDate and time (UTC) of transaction.String
updated_atDate and time (UTC) of transaction.String
hold_fx_ expires_onDate and time (UTC) of hold_fx expiryString

Allowed values for account_identifier_type under beneficiary based on corridor

CurrencyType
SGDMOBILE, UEN, NRIC, VPA
BRLMOBILE, EMAIL, ID
INRVPA
MYRNRIC, PASSPORT, CORPORATE_REGISTRATION_NUMBER, MOBILE, ARMY_ID
AUDMOBILE, EMAIL, ABN, ORGANISATION_ID
HKDEMAIL, MOBILE, FPS ID

Payout Rails Details​

By default, Nium selects the optimal payout rail for each transaction based on internal routing logic — factoring in cost, coverage, and speed. The Payout Rail Preference feature lets clients override this default and specify how their payments should be routed, per corridor or per payment.

This is useful when you need to guarantee real-time delivery, optimize for cost, or ensure consistent settlement behavior across a product line.

Why it matters​

Without rail preference, clients have limited visibility or control over which rail Nium uses. With this feature, you can:

  • Guarantee real-time routing for specific corridors (e.g. always use FPS for GBP, never CHAPS)
  • Optimize for cost or speed depending on your use case
  • Give your end users a predictable, consistent payment experience
  • Advertise specific SLAs confidently, knowing Nium will not silently downgrade the rail

How it works​

Include the payout_rail field in your Create Payment request. Nium validates the value against your client configuration and the destination corridor, then routes accordingly.

{  
"payout_rail": ["REALTIME"]
}

Corridor-agnostic values that Nium maps to the best available rail per destination.

ValueDescriptionBest For
REALTIMENear-instant settlement (e.g. FPS, FedNow, Interac)When settlement speed is the priority
SAMEDAYSame-day, batch-processed rails where schemes and cut-offs permitPayroll, batch payouts, end-of-day settlements
LOWCOSTLowest-cost available rail per corridorWhen cost is the priority and SLA allows standard settlement
SWIFTSettlement via the SWIFT networkCross-border payouts where local rails are unavailable, or high-value B2B transfers
LOCALStandard domestic clearing rails (e.g. ACH, SEPA Credit Transfer)Non-urgent domestic payouts where rail predictability matters more than speed or cost

Supported corridors and rail mapping​

Generic mode → rail mapping​

CurrencyREALTIMESAMEDAYLOWCOSTSWIFTLOCAL
EURINSTANTSTANDARDINSTANTSWIFTINSTANT, STANDARD
GBPFPSCHAPSFPSSWIFTFPS, CHAPS
HKDFPS, ACT, CHATSNot supportedFPS, ACTSWIFTFPS, ACT, CHATS
SGDFPSSFTPSFTPSWIFTFPS, SFTP
AUDNPPDEDESWIFTNPP, DE
CADINTERACEFTEFTSWIFTEFT
AEDIPPRTGSRTGSSWIFTRTGS
MYRDUITNOWRENTASGIROSWIFTDUITNOW, RENTAS
note

For AED transactions below 50,000 AED: if the beneficiary bank does not support real-time (IPP) settlement, the transaction will be routed via RTGS instead of being rejected.

Error handling​

Every rail preference is validated against your client configuration and corridor capabilities before the payout is processed. If the requested mode or rail is not supported, the request is rejected with a clear error — there is no silent downgrade or fallback.

Example error response:

{
"statusCode": 400,
"error": "Bad Request",
"message": "Invalid payout_rail [SWIFT_UK] for destination currency SGD. Allowed values: [FPS], [SFTP], [SWIFT], [FPS, SFTP]."
}

Best practices​

  • Use generic modes (REALTIME, LOCAL) over explicit rail IDs — they are corridor-agnostic and easier to maintain as your payment corridors expand.
  • Set corridor-level defaults during onboarding via your Nium account manager, then use transaction-level payout_rail to override for specific payments when needed.