Show Menu

Create ACH Debit Bank

Create ACH Debit Bank

Generally available June 2019 in USA and Canada. ACH Debit requires setup and approval. If you just made a request, please check your email inbox for next steps and also read below for a description of those steps. More Info.

post/API/v4/Bank/LinkACHDebitBankBeneficiary

Header Parameters

Authorizationstring

bearer access_token

Content-typestring

application/json

Request Parameters

IssuerAccountNumberstring

String length: inclusive between 1 and 25

UserIDstring

String length: inclusive between 1 and 25
If you are create bank beneficiary for a user PATXXXX. If you are creating bank beneficiary for a company use SPNXXXX.

Beneficiary Details

ContactNamestring

String length: inclusive between 1 and 100

PhoneNumberstring

String length: inclusive between 1 and 15

AddressLine1string

String length: inclusive between 1 and 35

AddressLine2string

String length: inclusive between 1 and 35

Citystring

String length: inclusive between 1 and 20

Regionstring

String length: inclusive between 1 and 30

PostalCodestring

String length: inclusive between 1 and 20

Regionstring

String length: inclusive between 1 and 30

CountryISO2string

String length: 2

Beneficiary Bank Information

InstitutionNamestring

String length: inclusive between 1 and 50

WithdrawTypestring

String length: inclusive between 1 and 4

Currencystring

String length: inclusive between 1 and 3

SWIFTBICstring

String length: inclusive between 1 and 12

AccountNumberstring

String length: inclusive between 1 and 50

RoutingNumberstring

String length: inclusive between 1 and 15

CountryISO2string

String length: 2

RemittanceLine3string

String length: inclusive between 1 and 50.

RemittanceLine4string

String length: inclusive between 1 and 50

Response Parameters

BeneficiaryIdstring

Returned if successful Unique identifier of the beneficiary that was created.

OperationStatusstring

Always returned Indicates the status of the operation. Allowed parameters are:
Errors - Displays an error message if the Property name Obligation Definition/value operation was unsuccessful. For more information, see API Error Message Appendix.
Success—Indicates whether the operation was successful. Returns True if the action was successful or False if it was not successful.

Use Case 1 – Routing Code & Account Number

This use case outlines a flow for a beneficiary in which the BankCountryCode and BeneficiaryCountryCode correspond to the ‘home’ country of the Currency.
E.G. USD sent to The United States, GBP sent to Great Britain, etc.

Five (5) key pieces of data are collected from the user. This determines what else is needed to complete the link bank.

BANKACCOUNTNUMBER

BANKCOUNTRYCODE

BENEFICIARYCOUNTRYCODE

BENEFICIARYNAME

CURRENCY

Sample Request: STEP 1

sandbox.xapi.xtrm.com/API/v4/Bank/LinkACHDebitBankBeneficiary

{  
  "LinkACHDebitBankBeneficiary":{  
    "request":{  
      "IssuerAccountNumber":"SPN Account Number",
      "UserID":"SPN/PAT Account Number",
      "Beneficiary":{  
        "BeneficiaryDetails":{  
          "BeneficiaryInformation":{  
            "ContactName":"Beneficiary Contact Name",
            "PhoneNumber":"Beneficiary Phone Number",
            "AddressLine1":"Beneficiary Address Line1",
            "AddressLine2":"Beneficiary Address Line2",
            "City":"Beneficiary City",
            "Region":"Beneficiary Region",
            "PostalCode":"Beneficiary PostalCode",
            "CountryISO2":"Two-letter ISO country code"
          }
        },
        "BankDetails":{  
          "BeneficiaryBankInformation":{  
            "InstitutionName":"Name of the institution",
            "Currency":"Three-letter currency code",
            "SWIFTBIC":"Unique identifier for the bank",
            "AccountNumber":"Bank account number",
            "RoutingNumber":"Bank routing code/National Bank Code",
            "CountryISO2":"Two-letter ISO country code",
            "RemittanceLine3":"Remittance Line3",
            "RemittanceLine4":"Remittance Line4"
          }
        }
      }
    }
  }
}
						

Sample Response:


{
	"LinkACHDebitBankBeneficiaryResponse": {
		"LinkACHDebitBankBeneficiaryResult": {
			"BeneficiaryId": null,
			"BankBeneficiaryStatus": null,
			"AccountIdentityLevel": null,
            "ACHDebitApprovalStatus": null
			"OperationStatus": {
				"Errors": [
					{
						"ErrorMessage": "BankRoutingCode / NationalID is required.",
						"FieldName": "RoutingNumber",
						"FieldLabel": "Routing Number"
					}
				],
				"Success": false
			}
		}
	}
}
						

‘Routingnumber’ is added in this call (in addition to previously submitted data per response).

Sample Request: STEP 2

sandbox.xapi.xtrm.com/API/v4/Bank/LinkACHDebitBankBeneficiary

{  
  "LinkACHDebitBankBeneficiary":{  
    "request":{  
      "IssuerAccountNumber":"SPN19134662",
      "UserID":"SPN19134662",
      "Beneficiary":{  
        "BeneficiaryDetails":{  
          "BeneficiaryInformation":{  
            "ContactName":"Beneficiary Contact Name",
            "PhoneNumber":"231231312",
            "AddressLine1":"Beneficiary Address Line1",
            "AddressLine2":"Beneficiary Address Line2",
            "City":"Belmont",
            "Region":"CA",
            "PostalCode":"131231",
            "CountryISO2":"US"
          }
        },
        "BankDetails":{  
          "BeneficiaryBankInformation":{  
            "InstitutionName":"wells fargo",
            "Currency":"USD",
            "SWIFTBIC":"",
            "AccountNumber":"121312312",
            "RoutingNumber":"143906",
            "CountryISO2":"US",
            "RemittanceLine3":"",
            "RemittanceLine4":""
          }
        }
      }
    }
  }
}
						

Sample Response:


{
	"LinkACHDebitBankBeneficiaryResponse": {
		"LinkACHDebitBankBeneficiaryResult": {
			"BeneficiaryId": "cdf85c46d30547ceadb586a0c28e1000",
			"BankBeneficiaryStatus": "Approved",
			"AccountIdentityLevel": "Standard",
			"ACHDebitApprovalStatus": "Pending: You will be notified once approved and then you can use FundWalletUsingACHDebit API call to fund your wallet.",
			"OperationStatus": {
				"Errors": null,
				"Success": true
			}
		}
	}
}					

Use Case 2 – SWIFTBIC & IBAN

This use case outlines a flow for a beneficiary in which the BankCountryCode and BeneficiaryCountryCode do not correspond to the ‘home’ country of the Currency. E.G. GBP sent to The United States, USD sent to Great Britain, etc.

Five (5) key pieces of data are collected from the user. This determines what else is needed to complete the link bank.

BANKACCOUNTNUMBER

BANKCOUNTRYCODE

BENEFICIARYCOUNTRYCODE

BENEFICIARYNAME

CURRENCY

Sample Request: STEP 1

sandbox.xapi.xtrm.com/API/v4/Bank/LinkACHDebitBankBeneficiary

 {  
  "LinkACHDebitBankBeneficiary":{  
    "request":{  
      "IssuerAccountNumber":"SPN15111156",
      "UserID":"PAT19134545",
      "Beneficiary":{  
        "BeneficiaryDetails":{  
          "BeneficiaryInformation":{  
            "ContactName":"Senthil V",
            "PhoneNumber":"Kumar M",
            "AddressLine1":"9 Laural court",
            "AddressLine2":"",
            "City":"Belmont",
            "Region":"California",
            "PostalCode":"99933",
            "CountryISO2":"US"
          }
        },
        "BankDetails":{  
          "BeneficiaryBankInformation":{  
            "InstitutionName":"Royal Bank of Scotland",
            "WithdrawType":"WIRE",
            "Currency":"GBP",
            "SWIFTBIC":"",
            "AccountNumber":"GB62RBOS83211600636614",
            "RoutingNumber":"",
            "CountryISO2":"GB",
            "RemittanceLine3":"",
            "RemittanceLine4":""
          }
        }
      }
    }
  }
}
						

Sample Response:


{
	"LinkACHDebitBankBeneficiaryResponse": {
		"LinkACHDebitBankBeneficiaryResult": {
			"BeneficiaryId": null,
			"BankBeneficiaryStatus": null,
			"AccountIdentityLevel": null,
            "ACHDebitApprovalStatus": null
			"OperationStatus": {
				"Errors": [
					{
						"ErrorMessage": "Beneficiary SWIFT BIC is required.",
						"FieldName": "SWIFTBIC",
						"FieldLabel": "SWIFTBIC"
					}
				],
				"Success": false
			}
		}
	}
}
						

‘SWIFTBIC’ is added in this call (in addition to previously submitted data per response).

Sample Request: STEP 2

sandbox.xapi.xtrm.com/API/v4/Bank/LinkACHDebitBankBeneficiary

 {  
  "LinkACHDebitBankBeneficiary":{  
    "request":{  
      "IssuerAccountNumber":"SPN15111156",
      "UserID":"SPN15111156",
      "Beneficiary":{  
        "BeneficiaryDetails":{  
          "BeneficiaryInformation":{  
            "ContactName":"Senthil V",
            "PhoneNumber":"Kumar M",
            "AddressLine1":"9 Laural court",
            "AddressLine2":"",
            "City":"Belmont",
            "Region":"California",
            "PostalCode":"99933",
            "CountryISO2":"US"
          }
        },
        "BankDetails":{  
          "BeneficiaryBankInformation":{  
            "InstitutionName":"Royal Bank of Scotland",
            "WithdrawType":"WIRE",
            "Currency":"GBP",
            "SWIFTBIC":"RBOSGB2L",
            "AccountNumber":"GB62RBOS83211600636614",
            "RoutingNumber":"",
            "CountryISO2":"GB",
            "RemittanceLine3":"",
            "RemittanceLine4":""
          }
        }
      }
    }
  }
}
						

Sample Response:


{
	"LinkACHDebitBankBeneficiaryResponse": {
		"LinkACHDebitBankBeneficiaryResult": {
			"BeneficiaryId": "22da22fc977a4914a4ae52bcde8bc734",
			"BankBeneficiaryStatus": "Approved",
			"AccountIdentityLevel": "Standard",
			"ACHDebitApprovalStatus": "Pending",
			"OperationStatus": {
				"Errors": null,
				"Success": true
			}
		}
	}
}