Useful XTRM API Documentation for Creating a Linked Beneficiary Bank

Create Bank Beneficiary

A structure that contains the information needed to create a new beneficiary template.

post/API/v4/Bank/LinkBankBeneficiary

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

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/LinkBankBeneficiary


 {  
  "LinkBankBeneficiary":{  
    "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":"Bank of America",
            "WithdrawType":"WIRE",
            "Currency":"USD",
            "SWIFTBIC":"",
            "AccountNumber":"23224242423",
            "RoutingNumber":"",
            "CountryISO2":"US",
            "RemittanceLine3":"",
            "RemittanceLine4":""
          }
        }
      }
    }
  }
}

Sample Response:


{
	"LinkBankBeneficiaryResponse": {
		"LinkBankBeneficiaryResult": {
			"BeneficiaryId": null,
			"BankBeneficiaryStatus": null,
			"AccountIdentityLevel": 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/LinkBankBeneficiary


 {  
  "LinkBankBeneficiary":{  
    "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":"Bank of America",
            "WithdrawType":"WIRE",
            "Currency":"USD",
            "SWIFTBIC":"",
            "AccountNumber":"23224242423",
            "RoutingNumber":"026009593",
            "CountryISO2":"US",
            "RemittanceLine3":"",
            "RemittanceLine4":""
          }
        }
      }
    }
  }
}

Sample Response:


{
	"LinkBankBeneficiaryResponse": {
		"LinkBankBeneficiaryResult": {
			"BeneficiaryId": "4e93b310148f4c7b934f25f61b8681b0",
			"BankBeneficiaryStatus": "Pending",
			"AccountIdentityLevel": "Pending",
			"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/LinkBankBeneficiary


 {  
  "LinkBankBeneficiary":{  
    "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:


{
	"LinkBankBeneficiaryResponse": {
		"LinkBankBeneficiaryResult": {
			"BeneficiaryId": null,
			"BankBeneficiaryStatus": null,
			"AccountIdentityLevel": 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/LinkBankBeneficiary


 {  
  "LinkBankBeneficiary":{  
    "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":"RBOSGB2L",
            "AccountNumber":"GB62RBOS83211600636614",
            "RoutingNumber":"",
            "CountryISO2":"GB",
            "RemittanceLine3":"",
            "RemittanceLine4":""
          }
        }
      }
    }
  }
}

Sample Response:


{
	"LinkBankBeneficiaryResponse": {
		"LinkBankBeneficiaryResult": {
			"BeneficiaryId": "4e93b310148f4c7b934f25f61b8681b0",
			"BankBeneficiaryStatus": "Pending",
			"AccountIdentityLevel": "Pending",
			"OperationStatus": {
				"Errors": null,
				"Success": true
			}
		}
	}
}

Use Case 3 – Exotic Currency Requirements

Some exotic currencies will require currency specific information in order to remit funds. Recommended Implementation: Display any special remittance information required on step 2 as you collect BankAccountNumber,BankRoutingNumber or BankSWIFTBIC.

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/LinkBankBeneficiary


 {  
  "LinkBankBeneficiary":{  
    "request":{  
      "IssuerAccountNumber":"SPN15111156",
      "UserID":"PAT19134545",
      "Beneficiary":{  
        "BeneficiaryDetails":{  
          "BeneficiaryInformation":{  
            "ContactName":"Senthil V",
            "PhoneNumber":"Kumar M",
            "AddressLine1":"9 Laural court",
            "AddressLine2":"",
            "City":"City",
            "Region":"Region",
            "PostalCode":"99933",
            "CountryISO2":"BR"
          }
        },
        "BankDetails":{  
          "BeneficiaryBankInformation":{  
            "InstitutionName":"Brazil Bank",
            "WithdrawType":"WIRE",
            "Currency":"BRL",
            "SWIFTBIC":"",
            "AccountNumber":"BR97 0036 0305 0000 1000 9795 493P 1",
            "RoutingNumber":"",
            "CountryISO2":"BR",
            "RemittanceLine3":"",
            "RemittanceLine4":""
          }
        }
      }
    }
  }
}

Sample Response:


{
	"LinkBankBeneficiaryResponse": {
		"LinkBankBeneficiaryResult": {
			"BeneficiaryId": null,
			"BankBeneficiaryStatus": null,
			"AccountIdentityLevel": null,
			"OperationStatus": {
				"Errors": [
					{
						"ErrorMessage": "Remittance Line 3 is required.",
						"FieldName": "RemittanceLine3",
						"FieldLabel": "Recipient Name and Phone Number"
					},
					{
						"ErrorMessage": "Remittance Line 4 is required.",
						"FieldName": "RemittanceLine4",
						"FieldLabel": "Tax ID Number"
					},
					{
						"ErrorMessage": "Beneficiary SWIFT BIC is required.",
						"FieldName": "SWIFTBIC",
						"FieldLabel": "SWIFTBIC"
					}
				],
				"Success": false
			}
		}
	}
}

‘RemittanceLine3’,‘RemittanceLine4’,‘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/LinkBankBeneficiary


 {  
  "LinkBankBeneficiary":{  
    "request":{  
      "IssuerAccountNumber":"SPN15111156",
      "UserID":"PAT19134545",
      "Beneficiary":{  
        "BeneficiaryDetails":{  
          "BeneficiaryInformation":{  
            "ContactName":"Senthil V",
            "PhoneNumber":"Kumar M",
            "AddressLine1":"9 Laural court",
            "AddressLine2":"",
            "City":"City",
            "Region":"Region",
            "PostalCode":"99933",
            "CountryISO2":"BR"
          }
        },
        "BankDetails":{  
          "BeneficiaryBankInformation":{  
            "InstitutionName":"Brazil Bank",
            "WithdrawType":"WIRE",
            "Currency":"BRL",
            "SWIFTBIC":"BRASBRRJXXX",
            "AccountNumber":"BR97 0036 0305 0000 1000 9795 493P 1",
            "RoutingNumber":"",
            "CountryISO2":"BR",
            "RemittanceLine3":"Contact Name and Phone",
            "RemittanceLine4":"Corporate Tax, Brand code"
          }
        }
      }
    }
  }
}

Sample Response:


{
	"LinkBankBeneficiaryResponse": {
		"LinkBankBeneficiaryResult": {
			"BeneficiaryId": "4e93b310148f4c7b934f25f61b8681b0",
			"BankBeneficiaryStatus": "Pending",
			"AccountIdentityLevel": "Pending",
			"OperationStatus": {
				"Errors": null,
				"Success": true
			}
		}
	}
}

Why

About

Customers

Partners

Assurance

People

Global Payments

Accounts Payables

Incentives

Pay Contractors

XTRM API TM

Getting Started

API Overview

Features & Benefits

Partners

Overview

Aggregate

Manage

Receive

Send

Tax

Security

Compliance

Payment Methods

Fees

Contact

Request Information or Demo

Blog

Blog

CASE STUDIES

Case Studies

Resource Library

E-books, Infographics & White Papers

Help

Help

Support

Support

Create Bank Beneficiary

Why

Products

Developers

How It Works

Resources

XTRM API ^TM