International Disbursements

API Implementation Guide

Empirical workflow

Payer Authentication:

Endpoint: https://sandboxapi.kyckglobal.com/apis/userAuth

Country Currency Check

Endpoint: https://sandboxapi.kyckglobal.com/apis/getPaymentMethodBasedCountry

Payee Onboarding

• Endpoint: https://sandboxapi.kyckglobal.com/apis/onboardPayeeWithBeneficiary
• Field Definitions
• Required Fields By Account Details

Create Payment (Disbursement)

Endpoint: https://sandboxapi.kyckglobal.com/apis/bulkPaymentByJSON

Get PayStub

Endpoint: https://sandboxapi.kyckglobal.com/apis/getPayStub/:Reference_Id

Cancel Payment

EndPoint: https://sandboxapi.kyckglobal.com/apis/cancelPayment/:Reference_Id

Payee Management APIs

1. Payer Authentication

Use the Auth Token Request operation to obtain an auth token. The auth token is used to authenticate your session on the Direct Send platform, and it must be refreshed every 1 hour. Send a POST request to the /userAuth endpoint with your Direct Send account email address and password in the body of the request.

JWT Lifetime:

1 Hour

Endpoint:

https://sandboxapi.kyckglobal.com/apis/userAuth

Request:

{
"email": "[userEmailAddress]",
"password": "[password]"
}

Response (successful result):

{
"success": true,
"token": "JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyVHlwZSI6Ikt5Y2siLCJlbWFpbCI6ImJlbHNpbmdlckBreWNrZ2xvYmFsLmNvbSIsInJvbGUiOiJLeWNrLVN1cGVyLUFkbWluIiwibG9naW5TdGF0dXMiOiJsb2dnZWRJbiIsImlhdCI6MTY2MjQ5MzYwMiwiZXhwIjoxNjYyNTgwMDAyfQ.bp14WXJEu1QiU_UfzjL6Es06vlVcRPj-jldljnF2D-c",
"user": {
"role": "Kyck-Super-Admin",
"userType": "Kyck"
}
}

2. Country Currency Coverage Check

The supported country / currency check for payments methods does a look up for all countries, and provides the list of payment methods & currencies (where applicable) that are supported for that country.

Endpoint:

https://sandboxapi.kyckglobal.com/apis/getpaymentMethodBasedCountry

Basic Request:

This request only includes a Header with the current JWT Token

Response (successful result):

{
"status": true,
"data": [
{
"countryName": "Puerto Rico",
"countryCode": "PRI",
"currency": "USD",
"pushToCard": false,
"pushToAccount": false,
"internationalIAch": false,
"internationalWire": true,
"payPal": false,
"cash": false,
"check": false,
"internationalBankAccount": false,
"employeePaycard": false,
"ach": true,
"ncrPay360": false,
"venmo": false,
"giftCard": false,
"reloadablePrepaidCard": false,
"cashSupportedReceiveCurrency": "USD",
"readyCode": false
},...

Field Definitions:

3. Create Single Payee

The Onboard Single Payee operation creates a new Payee record under the Payer Organization specified in the request body.

Endpoint:

https://sandboxapi.kyckglobal.com/apis/onboardPayeeWithBeneficiary

Basic Request:

This request sample has the minimum field requirements for adding a payee.

IBAN Details

{
"payerId": "{{uat_payerid}}",
"email": "[email protected]",
"account": {
"iban": "ES0200492666702094515427"
},
"firstName": "Brad",
"lastName": "Bene test",
"phone": "",
"address": "AV JANDIA S-N APDO. 00000",
"region": "Madrid",
"city": "Madrid",
"postalCode": "35625",
"classification": "Individual",
"paymentMethod": "E"
}

Routing/Account Number Details

{
"payerId": "{{uat_payerid}}",
"email": "[email protected]",
"account": {
"routingCode": "004958786",
"destinationCountry": "ES",
"accountNumber": "2416015745"
},
"firstName": "Brad",
"lastName": "Bene test",
"phone": "",
"address": "AV JANDIA S-N APDO. 00000",
"region": "Madrid",
"city": "Madrid",
"postalCode": "35625",
"classification": "Individual",
"paymentMethod": "E"
}

Field Definitions:

4. Create Payment (Disbursement)

The Create Payments operation initiates one or more payments to the payees defined in the request body. This operation can submit payments for processing on multiple dates.

Endpoint:

POST – /bulkPaymentByJSON

Request:

{
"payerId": "[payerId]",
"payments": [
{
"payeeDetails": {
"payeeId": "[payeeId]",
"email": "[payeeEmailAddress]",
"payeeName": "[payeeName]"
},
"paymentReason": "Payout",
"PaymentDescription": " ",
"paymentData": {
"effectivePaymentDate": "[effectivePaymentDate]",
"amount": 5.00,
"paymentType": "[paymentType]"
},
"payeeCurrency": "[ISO Alpha-3 Currency Code]"
}
]
}

5. Get Pay Stub

Request:

https://sandboxapi.kyckglobal.com/apis/getPayStub/{{Reference_ID}}

Response (standard):

{
"success": true,
"payStub": {
"payerACHApproved": true,
"returnedReason": "",
"status": "Submitted",
"responseData": "",
"createdBy": "",
"name": "",
"returnStatus": false,
"achType": "sameDay",
"flag": false,
"paymentStatus": false,
"paymentReason": "Payout",
"PayerCustomerId": "",
"fileId": "",
"payerTXId": "",
"payerId": "",
"payeeAccountNumber": "",
"payeeDetails": {
"payeeName": "",
"payeeId": "",
"email": "",
"PayeeFirstName": "",
"PayeeLastName": "r"
},
"payeePaymentMethod": "venmo",
"cashCreatedDate": "",
"requestedDate": "09/06/2022",
"createdByUserType": "",
"payerMailingAddress": {
"mailingAddressLineTwo": "Building 15 Suite P-120",
"mailingPostalCode": "30305",
"mailingState": "GA",
"mailingCity": "Atlanta",
"mailingAddressLineOne": "3575 Piedmont Rd NE ",
"mailingCountry": "USA"
},
"payPeriodTo": null,
"typeOfACH": "Disbursement",
"paymentCreatedDate": "09/06/2022",
"cashFetch": "",
"Reference_ID": "RAAJ5B4XDVOUTUVEN",
"frequencyOrDate": "NA",
"cashStatus": "",
"createdHour": "",
"paymentData": {
"amount": 5,
"effectivePaymentDate": "09/07/2022"
},
"requestedTime": "4:06:34 PM",
"payerEmail": "",
"accountName": "",
"datetimestamp": 1662494794257,
"AccountType": "”,
"payerName": "",
"payPeriodFrom": null,
"cashBatchId": "",
"PaymentDescription": "This is a check payment for your loan",
"collectionReference_ID": "",
"collectionStatus": "Submitted",
"pendingReason": "",
"pendingReference_ID": "",
"paymentReference_ID": "",
"PayerPaymentReferenceNum": "Loan Id: 1254620",
"Trace_ID": "",
"cashLocation": ""
}
}

Response (fail):

{
"success": false,
"msg": "Paystub is not found"
}

6. Cancel Payment

Endpoint:

https://sandboxapi.kyckglobal.com/apis/cancelPayment/{{Reference_ID}}

Response (success):

{
"success": true,
"message": "The Payment has been cancelled Successfully"
}

Response (fail):

{
"success": false,
"msg": "Reference id is invalid"
}

Appendix A – Applicable Disbursement Statuses

The following are the applicable disbursement status(es) supported by Direct Send:

Appendix B – Payee Management

C.1 Get Payee by Id

Request:

https://sandboxapi.kyckglobal.com/apis/getPayeeById/{{PayeeId}}

Response (success):

{
"success": true,
"data": [
{
"createdByName": "Brad Elsinger",
"pushToAccount": false,
"pushToCardAccount": [
{
"last4": "9913",
"allocation_version": "new",
"allocation": 100,
"isMasterCard": true,
"auditLog": [
{
"date": "2022-09-08T17:36:59.440Z",
"type": "create",
"user": "unknown name",
"email": "[email protected]"
}
],
"accountName": "PushToCard",
"createdTimeStamp": 1662658619440,
"allocationType": "percentage-allocation",
"type": "PushToCard",
"primaryAccount": false,
"accountStatus": "active",
"accountId": "acct_2Z10lU1zmOor_JCOOunma_i2Tpm",
"createdDate": "09/08/2022",
"accountApproved": true,
"createdTime": "1:36:59 PM",
"expirationDate": "2030-10"
}
],
"payerLegalName": "Brad's Test Company",
"payeeOnboardedDate": "09/08/2022",
"payeeInternationalAch": false,
"createdBy": "[email protected]",
"payeeInternationalBank": false,
"payeeNcrPay360Account": [
{
"accountStatus": "active",
"allocation_version": "old",
"allocation": 0,
"accountApproved": true,
"auditLog": [
{
"date": "2022-09-08T17:31:04.511Z",
"type": "create",
"user": "unknown name",
"email": "[email protected]"
}
],
"accountName": "NCRpay360",
"accountNumber": "4044015555",
"allocationType": "percentage-allocation",
"type": "NCRpay360",
"primaryAccount": false
}
],
"contactInfo": [
{
"contactNumber": "1234567890",
"contactType": "Mobile"
}
],
"payeeDisabled": false,
"payeeCheck": false,
"enableConvenienceFeeToAllPayee": false,
"payeeIncommCL": false,
"payerId": "Payer00253",
"payeePushDebit": false,
"payeeDetails": {
"isDBAasReceiverEnabled": false,
"sendSMS": true,
"contactInfo": [
{
"contactNumber": "1234567890",
"contactCode": "+1",
"contactType": "Mobile"
}
],
"payeeFirstName": "",
"payeeLastName": "",
"payeereferenceId": "5648375568",
"pstate": "GA",
"pcountry": "USD",
"pemail": "[email protected]",
"mcountry": "USD",
"mstate": "GA"
},
"payeeId": "Payee25301bthh",
"payeeInternationalWire": false,
"accountActive": false,
"createdByUserType": "Kyck-Super-Admin",
"payeeNcrPay360": true,
"payeeAch": false,
"blockNotification": false,
"payeeLastName": "elsinger",
"payeeEmail": "[email protected]",
"payeeFirstName": "Bradley",
"payeeVenmo": false,
"payeeDestinationCountry": "US",
"pushToCard": true,
"payeeEmployeePayCard": false,
"payeeMoneyGram": null,
"payeeMoneyGramAccount": null,
"payeePayPal": false,
"payeeReloadablePrepaidCard": false,
"payeeReferenceId": "5648375568",
"payeeStatus": "Onboarded",
"datetimestamp": 1662658264564,
"payeePaymentPreferences": {
"pushToCardStatus": true,
"venmoStatus": false,
"pach": false,
"pmoney": null,
"incommCLStatus": false,
"pushDebitStatus": false,
"iACHStatus": false,
"reloadablePrepaidCardStatus": false,
"checkStatus": false,
"ncrPay360Status": false,
"wireStatus": false,
"internationalBankStatus": false,
"pushToAccountStatus": false,
"employeePayCardStatus": false,
"paymentFreference": "Monthly",
"payPalStatus": false,
"pcash": true
},
"payeeFinancialAccountStatus": "Approved",
"payeeCash": true,
"payeeCashAccount": [
{
"accountStatus": "active",
"allocation_version": "old",
"allocation": 0,
"accountApproved": true,
"auditLog": [
{
"date": "2022-09-08T17:31:04.511Z",
"type": "create",
"user": "unknown name",
"email": "[email protected]"
}
],
"accountName": "incomm",
"allocationType": "percentage-allocation",
"type": "Cash",
"primaryAccount": true
}
]
}
]
}

Response (fail):

{
"success": false,
"message": "Payee not Found"
}

C.2 Update Payee

Endpoint:

PUT – https://sandboxapi.kyckglobal.com/apis/updatePayeeWithBeneficiary

Request:
IBAN Details

{
"payerId": "{{uat_payerid}}",
"payeeId": "Payeeeece07b0-84f3-4509-a14b-0e8ab2a3a23d",
"account": {
"iban": "ES0200492666702094515427"
},
"firstName": "Brad",
"lastName": "Bene test",
"phone": "",
"address": "AV JANDIA S-N APDO. 00000",
"region": "Madrid",
"city": "Madrid",
"postalCode": "35625",
"classification": "Individual",
"paymentMethod": "E"
}

Routing/Account Number Details
{
"payerId": "{{uat_payerid}}",
"payeeId": "Payeeeece07b0-84f3-4509-a14b-0e8ab2a3a23d",
"account": {
"routingCode": "004958786",
"destinationCountry": "ES",
"accountNumber": "2416015745"
},
"firstName": "Brad",
"lastName": "Bene test",
"phone": "",
"address": "AV JANDIA S-N APDO. 00000",
"region": "Madrid",
"city": "Madrid",
"postalCode": "35625",
"classification": "Individual",
"paymentMethod": "E"
}
Response (success):
{
"success": true,
"message": "Payee profile successfully Updated.",
"warnings": []
}

C.3 Update Payee Account Allocation

NOTE: Sum of allocations in the allocation object must equal 0 or 100!

Switching Account Allocation From One Account to Another

Endpoint:

PUT –apis/singlePayeeUpdate

Request Body:

{
"payerId": "{{payerId}}",
"payeeId": "{{payeeId}}",
"allocationWithAccountId": [
{
"payeeDisbursementAccountId": 1,
"allocation": 100
},
{
"payeeDisbursementAccountId": 2,
"allocation": 0
}
]
}

Splitting Account Allocation across Payee Accounts

Endpoint:

PUT –/apis/singlePayeeUpdate

Request Body:

{
"payerId": "{{payerId}}",
"payeeId": "{{payeeId}}",
"allocationWithAccountId": [
{
"payeeDisbursementAccountId": 1,
"allocation": 50
},
{
"payeeDisbursementAccountId": 2,
"allocation": 50
}
]
}

C.4 Soft Delete Payee

Endpoint:

POST – /apis/payerPayeeUpdateStatus

Request Body:

{
"payeeId": "[payeeId]l",
"payerId": "[payerId]",
"payeeDisabled": true
}