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": "マーク ジョブス"
},
    "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"
    },
    "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" : ["FEDWIRE"]
}'

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
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
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:\n\nUSD: ['FEDWIRE', 'FEDNOW', 'ACH'],\n\nCAD: ['INTERAC', 'EFT']Array<String>No

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