Payments Quickstart
This guide demonstrates how to use Modern Treasury's API to open an account and create your first payment.
1. Retrieve your API Key
Once you have access to Modern Treasury, log in and go to your API Keys page. There you will find your Organization ID and API keys.
Authentication with the Modern Treasury API is done by using HTTP Basic authentication, with your Organization ID as the username and the API Key as the password. When using curl, you can use the -u option to pass these values directly.
If using one of our server side SDKs, you can either pass these values in directly, or the library will pull from defined environment variables.
curl --request GET \
-u $ORGANIZATION_ID:$API_KEY \
--url https://app.moderntreasury.com/api/pingfrom modern_treasury import ModernTreasury
modern_treasury = ModernTreasury(
# defaults to os.environ.get("MODERN_TREASURY_API_KEY")
api_key="your-api-key",
organization_id="your-organization-id",
)
pong = modern_treasury.ping()
print(pong)import ModernTreasury from 'modern-treasury';
const modernTreasury = new ModernTreasury({
apiKey: 'your-api-key', // defaults to process.env["MODERN_TREASURY_API_KEY"]
organizationId: 'your-organization-id',
});
async function main() {
const pong = await modernTreasury.ping()
console.log(pong);
}
main().catch(console.error);2. Open an Account
In order to move money with Modern Treasury you must open an account linked to the entity that is operating the account and on whose behalf the funds are held. Refer to our guide on opening accounts for detailed instructions over onboarding users and opening accounts. See below for instructions on creating the required legal entity and opening your first account.
Create a Legal Entity
The first step to opening an account is to create a legal entity which represents the business or individual that is tied to the account. For a business, the following call will create a legal entity with Modern Treasury and submit the entity for review:
curl --request POST \
--url https://app.moderntreasury.com/api/legal_entities \
--header 'content-type: application/json' \
--user $ORGANIZATION_ID:$API_KEY \
--data '
{
"legal_entity_type": "business",
"date_formed": "1800-01-01",
"business_name": "Hogwarts",
"legal_structure": "corporation",
"phone_numbers": [
{
"phone_number": "+14185438090"
}
],
"email": "[email protected]",
"website": "http://www.hogwarts.com",
"intended_use": "Payment operations and treasury management",
"expected_activity_volume": 1000000000,
"country_of_incorporation": "US",
"operating_jurisdictions": [
"US"
],
"wealth_and_emplyoment_details":
{
"source_of_funds": "business_revenue"
},
"documents":[
{
"document_type": "articles_of_incorporation",
"file_data": "dGVzdA==\n",
"filename": "articles_of_incorporation.pdf"
},
{
"document_type": "proof_of_address",
"file_data": "dGVzdA==\n",
"filename": "proof_of_address.pdf"
}
],
"addresses": [
{
"primary": true,
"line1": "119 5th Ave",
"line2": "Suite 600",
"locality": "New York",
"region": "NY",
"postal_code": "10011",
"country": "US",
"address_types": ["residential"]
}
],
"identifications": [
{
"id_type": "us_ein",
"issuing_country": "US",
"id_number": "123456789",
"documents": []
}
],
"legal_entity_associations": [{
"relationship_types": ["control_person"],
"child_legal_entity": {
"legal_entity_type": "individual",
"first_name": "Harry",
"middle_name": "James",
"last_name": "Potter",
"date_of_birth": "1990-02-06",
"email": "[email protected]",
"phone_numbers": [
{ "phone_number": "+14185438090"}
],
"addresses": [
{
"line1": "119 5th Ave",
"line2": "Suite 600",
"locality": "New York",
"region": "NY",
"postal_code": "10003",
"country": "US",
"address_types": ["residential"],
"primary": true
}
],
"identifications": [
{
"id_number": "111111111",
"id_type": "passport",
"issuing_country": "US",
"documents": [
{
"document_type": "identification_front",
"file_data": "dGVzdA==\n",
"filename": "passport.pdf"
}
]
}]}},
{
"relationship_types": ["beneficial_owner"],
"child_legal_entity": {
"legal_entity_type": "individual",
"first_name": "Albus",
"middle_name": "Percival",
"last_name": "Dumbledore",
"date_of_birth": "1881-07-01",
"email": "[email protected]",
"phone_numbers": [
{ "phone_number": "+14185438090"}
],
"addresses": [
{
"line1": "119 5th Ave",
"line2": "Suite 600",
"locality": "New York",
"region": "NY",
"postal_code": "10003",
"country": "US",
"address_types": ["residential"],
"primary": true
}
],
"identifications": [
{
"id_number": "111222333",
"id_type": "us_ssn",
"issuing_country": "US"
},
{
"id_number": "DL123456789",
"id_type": "drivers_license",
"issuing_country": "US",
"documents":[
{
"document_type": "identification_front",
"file_data": "dGVzdA==\n",
"filename": "license_front.pdf"
},
{
"document_type": "identification_back",
"file_data": "dGVzdA==\n",
"filename": "license_back.pdf"
}
]
}
]
}
}
]
}'In response, you will receive the following information:
{
"id": "<Legal Entity ID>",
"object": "legal_entity",
"status": "pending"
}In the sandbox environment legal entities will automatically transition to "status": "active", signaling that the legal entity has been approved and can be used to open an account. In production this state transition will occur after Modern Treasury has completed KYC/KYB verification on the entity. Refer to our detailed onboarding guides for more information on monitoring legal entity status.
Create an Internal Account
After the legal entity has been activated you can now open an account for the given entity. The below request will open a USD account:
curl --location 'https://app.moderntreasury.com/api/internal_accounts' \
--header 'Content-Type: application/json' \
--user $ORGANIZATION_ID:$API_KEY \
--data '{
"currency": "USD",
"legal_entity_id": "<Legal Entity ID>"
}'In response, you will receive the following information:
{
"id": "<Internal Account ID>",
"object": "internal_account",
"routing_details": [
{
"routing_number_type": "aba",
"routing_number": "021214891"
}
],
"account_details": [
{
"account_number": "<Unique Account Number>"
}
]
}3. Create a Counterparty
Now that the account has been opened, you may fund the account with an ACH Debit Payment Order. In order to initiate the payment, you must first create a Counterparty containing the Legal Entity’s bank account information:
curl --location 'https://app.moderntreasury.com/api/counterparties' \
--header 'Content-Type: application/json' \
--user $ORGANIZATION_ID:$API_KEY \
--data '{
"legal_entity_id": "<Legal Entity ID>",
"accounts": [
{
"account_type": "checking",
"routing_details": [
{
"routing_number_type": "aba",
"routing_number": "121141822"
}
],
"account_details": [
{
"account_number": "123456789"
}
]
}
]
}'In response you will receive the following information:
{
"id": "<Counterparty ID>",
"object": "counterparty",
"accounts": [
{
"id": "<External Account ID>",
"object": "external_account"
}
]
}4. Fund the Account
Now that all necessary objects have been created, you are able to execute your first ACH debit to fund the account. You will create a payment order. Note that amounts are given in the smallest unit of the currency, so for $100.00, the amount field would be 10000.
curl --location 'https://app.moderntreasury.com/api/payment_orders' \
--header 'Content-Type: application/json' \
--user $ORGANIZATION_ID:$API_KEY \
--data '{
"type": "ach",
"amount": 10000,
"direction": "debit",
"currency": "USD",
"originating_account_id": "<Internal Account ID>",
"receiving_account_id": "<External Account ID>"
}'In response you will get the following information:
{
"id": "<Payment Order ID>",
"object": "payment_order",
"status": "approved"
}In the sandbox payment orders will complete quickly and you can subscribe to webhooks over status changes like the below example:
{
"event": "completed",
"data": {
"id": "<Payment Order ID>",
"object": "payment_order",
"status": "completed"
}
}After the payment order has reached a completed state, you have successfully funded the account and will be able to create outbound payments.
Updated 2 days ago