Guides

Bring Your Own Payments

If you have built out your own payment rails, you can use Mercoa to orchestrate and trigger your custom payment rails. This lets you take advantage of Mercoa’s invoice management, payment tracking, and webhook functionality while using payment rails provided by you, your banking partner, or your payment processor.

At this time, custom payment rails cannot be used with Mercoa’s built-in payment rails in the same invoice.


Entities that only use custom payment rails do not need to go through Mercoa’s KYB/KYC checks. When creating entities that will only use custom payment rails, you only need to provide the required parameters and can skip adding EINs, representatives, etc.

How it works

In order to create a custom payment rail, you must first define a schema for your payment rail. This schema will be used to validate the payment rail data that you send to Mercoa. You can then use this schema to create a custom paymentMethod in Mercoa. Once the paymentMethod is created, you can use it to create an invoice.

Custom payment rails are designed to be used along with our webhooks functionality. When an invoice created with a custom rail is set to the pending status, Mercoa will send a webhook notification to your system. Your system can then use the webhook notification to trigger the payment using your custom payment rail. Once the payment is complete, your system needs to update the invoice as paid.

Creating a custom payment rail schema

API Reference

A custom payment rail schema is a set of key/value pairs that define the data that is required to trigger a payment using your custom payment rail.

For example, if you are using a custom payment rail to trigger a wire transfer, you might require the following data:

  • accountNumber
  • routingNumber
  • recipientName
  • recipientAddressLine1
  • recipientAddressLine2
  • recipientCity
  • recipientStateorProvince
  • recipientPostalCode
  • recipientCountry

Because a wire transfer is used to send money from one bank account to another, you would define the schema as a destination payment method. Schemas can be defined as a source or destination or both.

You can define this schema using the POST /paymentMethod/schema endpoint:

$curl --request POST \
>     --url https://api.mercoa.com/paymentMethod/schema \
>     --header 'Authorization: Bearer AUTH_VALUE' \
>     --header 'Content-Type: application/json' \
>     --data '{
> "name": "Wire Transfer",
> "isSource": false,
> "isDestination": true,
> "fields": [
>  {"name":"accountNumber","displayName":"Account Number","type":"text","optional":false},
>  {"name":"routingNumber","displayName":"Routing Number","type":"text","optional":false},
>  {"name":"recipientName","displayName":"Recipient Name","type":"text","optional":false},
>  {"name":"recipientAddressLine1","displayName":"Address Line One","type":"text","optional":false},
>  {"name":"recipientAddressLine2","displayName":"Address Line Two","optional":true,"type":"text"},
>  {"name":"recipientCity","displayName":"City","type":"text","optional":false},
>  {"name":"recipientStateorProvince","displayName":"State or Province","type":"text","optional":false},
>  {"name":"recipientPostalCode","displayName":"Postal Code","type":"text","optional":true},
>  {"name":"recipientCountry","displayName":"Country","type":"text","optional":true}]
>}'

Mercoa uses this schema information to automatically create UI elements for the paymentMethod that you create using this schema.

Creating a paymentMethod with a custom payment rail

API Reference

Once you have defined a custom payment rail schema, you can create a paymentMethod that uses that schema. The custom paymentMethod will contain the data that is required to trigger a payment using your custom payment rail, and a foreignId that can be used to identify the payment method in your system.

The foreignId is a unique identifier for the payment method in your system. It is used to identify the payment method in your system when you receive a webhook notification.


This paymentMethod can then be used as the paymentMethodSource or paymentMethodDestination when creating an invoice. Mercoa will validate the data that you send against the schema that you defined.

For example, once you have defined a custom payment rail schema for a wire transfer, you can create a paymentMethod that uses that schema using the POST /paymentMethod endpoint:

$curl --request POST \
>     --url https://api.mercoa.com/entity/{entityId}/paymentMethod \
>     --header 'Authorization: Bearer AUTH_VALUE' \
>     --header 'Content-Type: application/json' \
>     --data '{
> "type": "custom",
> "custom": {
>  "foreignId": "123456",
>  "accountName": "string",
>  "accountNumber": "string",
>  "schemaId": "cpms_35bf4ea1-cafe-4446-b90d-6d0fd08ee9a0",
>  "data": {
>    "accountNumber": "1234567890"
>    "routingNumber": "123456789"
>    "recipientName": "John Doe"
>    "recipientAddressLine1": "123 Main St"
>    "recipientAddressLine2": "Apt 1"
>    "recipientCity": "San Francisco"
>    "recipientStateorProvince": "CA"
>    "recipientPostalCode": "94105"
>    "recipientCountry": "US"
>  }
> }
>}'

In this example, the foreignId is 123456, and the schemaId is cpms_35bf4ea1-cafe-4446-b90d-6d0fd08ee9a0.

Next steps

You can now use this paymentMethod just like any other payment method on an invoice! When the invoice is set to the pending status, Mercoa will send a webhook notification to your system.

In order to have Mercoa generate the UI elements for both the payer and the vendor, the custom schema must be activated on the Payments Methods Dashboard.

Built with