Sign in

v1

latestOpenAPI 3.0.12026-07-26106359429.8 KB
Blockchain Payment

Create a Blockchain Payment

Creates a blockchain payment for fiat or cross-border payments.

post/v0/blockchain_payments

Headers

Idempotency-Keystring required

Idempotency key

Request body

referencestring

An optional reference message for the transfer, passed on to the recipient on rails that carry a reference.

Formatting requirements depend on creditor.payment_rail. The reference is stored and delivered exactly as submitted — it is never shortened, stripped, or otherwise altered. A reference that does not meet its rail's requirements is rejected when the payment is created, with HTTP 422 and an invalid_parameters entry for reference.

payment_railLengthAllowed characters
ach1–10letters, digits, spaces
wire1–140any character (line-formatted, see below)
iban6–140letters, digits, spaces, and & - . /
clabe1–40letters, digits, spaces
swift1–190letters, digits, spaces, and / - ? : ( ) . , ' + (line-formatted, see below)
pix_key1–100letters, digits, spaces
pix_br_code1–100letters, digits, spaces
fps1–18letters, digits, spaces

Additional rules:

  • wire and swift references are formatted into at most 4 lines of 35 characters. Words are kept whole and wrapped at spaces; include your own line breaks (\n) to control the layout. A single word longer than 35 characters, or text that cannot fit within 4 lines, is rejected.
  • iban requires a minimum of 6 characters. If you omit the reference on an iban payment, one is generated for you and returned on the created payment object.
  • bre_b, ethereum, base, and solana do not carry a reference; supplying one is rejected.
  • Omitting the field, or sending an empty string, is allowed on every rail except iban and results in no reference being sent.

Example request

{
  "debtor": {
    "account_identifier": {
      "type": "account_number_id",
      "value": "account_number_xyz123"
    },
    "chain": "ethereum",
    "refund_wallet_address": "0xabc123def456",
    "entity_id": "entity_xyz123"
  },
  "creditor": {
    "payment_rail": "wire",
    "ach_wire": {
      "account_number": "123456789",
      "routing_number": "021000021"
    },
    "ach": {
      "account_number": "123456789",
      "routing_number": "021000021"
    },
    "wire": {
      "account_number": "123456789",
      "routing_number": "021000021"
    },
    "bre_b": {
      "bre_b_key": "1234567890"
    },
    "fps": {
      "account_number": "12345678",
      "sort_code": "123456"
    },
    "iban": {
      "account_number": "DE89370400440532013000",
      "country": "DE",
      "business_identifier_code": "COBADEFFXXX"
    },
    "swift": {
      "account_number": "123456789",
      "country": "GB",
      "business_identifier_code": "BARCGB22XXX",
      "role": "client",
      "purpose_of_funds": "invoice_for_goods_and_services",
      "short_business_desc": "Software development services"
    },
    "clabe": {
      "account_number": "032180000118359719"
    },
    "pix_key": {
      "pix_key": "12345678909",
      "document_number": "12345678901"
    },
    "pix_br_code": {
      "br_code": "00020126580014br.gov.bcb.pix...",
      "document_number": "12345678901"
    },
    "co_bank_transfer": {
      "account_number": "1234567890",
      "bank_code": "1007",
      "account_type": "savings",
      "document_type": "cc",
      "document_number": "12345678901",
      "phone_number": "+573001234567"
    },
    "wallet": {
      "wallet_address": "0xdef456abc789"
    },
    "type": "individual",
    "individual": {
      "first_name": "Maria",
      "last_name": "Garcia"
    },
    "business": {
      "business_name": "Acme International LLC"
    },
    "address": {
      "line_one": "123 Main St",
      "line_two": "Suite 100",
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "postal_code": "94105"
    }
  },
  "creditor_agent": {
    "bank_name": "Banco Nacional de Mexico",
    "country_code": "MX",
    "address": {
      "line_one": "123 Main St",
      "line_two": "Suite 100",
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "postal_code": "94105"
    }
  },
  "amounts": {
    "instructed_amount": 100000,
    "instructed_currency_code": "USD",
    "settlement_currency_code": "MXN"
  },
  "payment_purpose": {
    "type": "invoice_payment",
    "other_details": "Monthly vendor payment"
  },
  "reference": "INV2024001"
}

Response

Successful response

idstring

The ID of the Blockchain Payment object.

referencestring

The reference message for the transfer. For iban payments created without a reference, this is a value generated automatically at creation, of the form Payment via Lead <payment id> (the payment's public ID with underscores replaced by hyphens, e.g. Payment via Lead blockchain-payment-2x7abc...). See reference on the create request for the per-rail formatting rules.

status'created' | 'under_review' | 'awaiting_funds' | 'submitted' | 'posted' | 'rejected' | 'canceled'

The current status of the blockchain payment.

rejection_reasonstring

Human-readable reason the payment was rejected. Present only when status is rejected.

This is a free-text field. Alongside the documented values below it may carry a return reason passed through from the receiving institution, so do not treat the set of values as closed or match on it programmatically for control flow.

Rejections fall into two classes:

  • Retryable — the payment was rejected for a condition that can clear on its own. You may submit the same payment again (a new create request with a new Idempotency-Key); it can succeed on a later attempt.
  • Terminal — submitting the same payment again will be rejected for the same reason. You must change the request, or the beneficiary's account must change, before a payment to that beneficiary can succeed.
rejection_reasonMeaningRetryable
name could not be validatedThe beneficiary name on the destination account had not finished verification when the payment was processed.Yes — submit the same payment again; it will succeed once verification completes.
name in request and name on account do not matchThe beneficiary name you supplied does not match the name on the destination account.No — submit a new payment with the correct beneficiary name.
account closedThe beneficiary's destination account is closed.No — use a different destination account.
payment could not be processedThe payment could not be completed.No
cancelation_reasonstring

Reason the transfer was canceled. Present only if status is canceled.

created_atstring date-time

ISO 8601 format timestamp representing when the blockchain payment was created.

updated_atstring date-time

ISO 8601 format timestamp representing when the blockchain payment was last updated.

Example response

{
  "id": "blockchain_payment_xyz123",
  "debtor": {
    "account_identifier": {
      "type": "account_number_id",
      "value": "account_number_xyz123"
    },
    "chain": "ethereum",
    "refund_wallet_address": "0xabc123def456",
    "funding_instructions": {
      "from_wallet_address": "0xabc123def456",
      "chain": "ethereum",
      "amount": "100.00",
      "currency_code": "USDC",
      "to_wallet_address": "0xdef456abc789"
    },
    "entity_id": "entity_xyz123"
  },
  "creditor": {
    "payment_rail": "wire",
    "ach_wire": {
      "account_number": "123456789",
      "routing_number": "021000021"
    },
    "ach": {
      "account_number": "123456789",
      "routing_number": "021000021"
    },
    "wire": {
      "account_number": "123456789",
      "routing_number": "021000021"
    },
    "bre_b": {
      "bre_b_key": "1234567890"
    },
    "fps": {
      "account_number": "12345678",
      "sort_code": "123456"
    },
    "iban": {
      "account_number": "DE89370400440532013000",
      "country": "DE",
      "business_identifier_code": "COBADEFFXXX"
    },
    "swift": {
      "account_number": "123456789",
      "country": "GB",
      "business_identifier_code": "BARCGB22XXX",
      "role": "client",
      "purpose_of_funds": "invoice_for_goods_and_services",
      "short_business_desc": "Software development services"
    },
    "clabe": {
      "account_number": "032180000118359719"
    },
    "pix_key": {
      "pix_key": "12345678909",
      "document_number": "12345678901"
    },
    "pix_br_code": {
      "br_code": "00020126580014br.gov.bcb.pix...",
      "document_number": "12345678901"
    },
    "co_bank_transfer": {
      "account_number": "1234567890",
      "bank_code": "1007",
      "account_type": "savings",
      "document_type": "cc",
      "document_number": "12345678901",
      "phone_number": "+573001234567"
    },
    "wallet": {
      "wallet_address": "0xdef456abc789"
    },
    "type": "individual",
    "individual": {
      "first_name": "Maria",
      "last_name": "Garcia"
    },
    "business": {
      "business_name": "Acme International LLC"
    },
    "address": {
      "line_one": "123 Main St",
      "line_two": "Suite 100",
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "postal_code": "94105"
    }
  },
  "creditor_agent": {
    "bank_name": "Banco Nacional de Mexico",
    "country_code": "MX",
    "address": {
      "line_one": "123 Main St",
      "line_two": "Suite 100",
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "postal_code": "94105"
    }
  },
  "amounts": {
    "instructed_amount": 100000,
    "instructed_currency_code": "USD",
    "settlement_currency_code": "MXN",
    "settlement_amount": 100000,
    "settlement_exchange_rate": "1.00"
  },
  "payment_purpose": {
    "type": "invoice_payment",
    "other_details": "Monthly vendor payment"
  },
  "reference": "INV2024001",
  "status": "created",
  "rejection_reason": "name could not be validated",
  "cancelation_reason": "Requested by customer",
  "created_at": "2024-06-27T11:22:33Z",
  "updated_at": "2024-06-27T11:22:33Z"
}