Create a transaction

Scope: Send Money (Requires IP Whitelist)

🚧

Valid uses for the transaction API

You may not use the Mercury API for any activity that requires a license or registration from any governmental authority in the U.S., or any authority you are subject to, without Mercury's approval in advance. This includes but is not limited to any activity type described in the definition of a Money Services Business, or any State-regulated financial services such as Money Transmission.

Here are some acceptable uses:

1. Paying invoices for your company
2. Automating bills and other payments

Here are some unacceptable uses:

1. Providing cash advances
2. Currency conversion services
3. Escrow services
4. Building out marketplaces to facilitate payments
   1. Marketplace - Any business model that involves receiving currency (or other value that substitutes for currency), and transferring that currency to another person by any means, including through a mobile application, through a network of persons, or through an informal value transfer system

Contact [email protected] if you'd like to confirm your use case is allowed. We especially recommend this if you'd describe your company as a financial services company.

Note that attempting to create a duplicate transaction (same recipient, same account, same amount) within 24 hours would result in an HTTP 400 error, even if you use different idempotency keys for each attempt. If you want this restriction removed, please reach out to our support.

📘

Idempotency Keys

Each request to create a transaction must provide an idempotency key which uniquely identifies the transaction. Repeated requests with the same idempotency key will not create a duplicate transaction, and will instead return HTTP 409 (conflict) with the normal API response for that transaction.

This approach makes it safe to retry creating a transaction, in case it is unclear that the transaction processed (for example, in case of a network error or your server crashing after the request is sent).

The idempotency key itself can be any value uniquely identifying the transaction. We recommend a UUID V4 or auto-incrementing database column for a general purpose solution.

Alternatively, you can also use a more semantic key. For example, if you pay Recipient A monthly, your idempotency key could be "Recipient A January". This would prevent duplicate transactions if you accidentally tried to pay Recipient A twice in January by mistake.

Your code should look something like this:

1. Insert a record of attempting a transaction into your database. This should include your own metadata about the transaction (e.g. recipient ID, amount, etc.), plus an idempotency key and a value noting that the transaction hasn't been attempted. Example query using PostgreSQL:

INSERT INTO transactions (id, recipient_id, amount, attempted) VALUES (uuid_generate_v4(), recip1, 10.20, false) RETURNING id;

2. Make the HTTP request to Mercury to create the transaction

3. Update the database record to note that the transaction was attempted. Example using PostgreSQL:

UPDATE transactions SET attempted = true WHERE id = <id from step 1>

You should set up some sort of alert or retry logic to look for transactions that are in your database, but are not marked as attempted (step 3). This case should be extremely rare, but because of the severity of duplicated transactions, this check is an important safeguard.