Skip to main content
POST
/
v1
/
payment_instructions
Create payment instructions
curl --request POST \
  --url https://api.nova.net/v1/payment_instructions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "entity": "ent_H0hdMOc5E5QMTEcGVZKegvLNCB6p",
    "payment_instructions": [
      {
        "type": "<string>",
        "beneficiary_name": "Jane Doe",
        "account_number": "123456789",
        "bank_name": "Bank of America",
        "branch_code": "123456",
        "external_reference": "payment-instructions-123",
        "routing_number": "021000021"
      }
    ]
  }
]
'
{
  "object": "list",
  "data": [
    {
      "object": "entity_payment_instructions",
      "livemode": true,
      "entity": "ent_H0hdMOc5E5QMTEcGVZKegvLNCB6p",
      "payment_instructions": {
        "object": "list",
        "data": [
          "pmi_021wlGURMlk80cYuKBjENXqwC3OV"
        ],
        "has_more": true,
        "url": "/v1/entities/ent_123/payment_instructions"
      }
    }
  ],
  "has_more": true,
  "url": "/v1/payment_instructions"
}

Authorizations

​
Authorization
string
header
required

OAuth2 client_credentials grant for server-to-server access. Onboard via your Nova admin to receive a client_id and client_secret, then POST /oauth/token to exchange them for a short-lived access token. Send the token as Authorization: Bearer <access_token> on every authenticated request. Tokens expire after 3600 seconds — refresh by re-exchanging credentials.

Headers

​
X-Organization-Id
string

ID of the organization the request acts on. Optional when the access token is bound to a specific organization, or when the integration has access to exactly one organization.

Pattern: ^org_[A-Za-z0-9]+$
Example:

"org_Xk7d2pQR9m3nBwYz"

​
Idempotency-Key
string

Supply a unique key to make a mutating request safely retryable. Any retry that sends the same key returns that stored response without performing the operation again.

  • Retention: keys are kept for 24 hours. Within that window a retry replays the original response.
  • Same key, different request: reusing a key with a different request body returns a 409 with code idempotency_mismatch. Use a fresh key for each distinct operation.
  • Still processing: if the first request has not finished, a retry returns 409 with code conflict (wait briefly and retry).
  • Server or transient errors (5xx, 408, 429) are not stored, so you may retry with the same key and the operation will be attempted again.

Only applies to POST, PUT, PATCH, and DELETE; ignored on reads.

Body

application/json
Minimum array length: 1
​
entity
string
required

ID of the entity

Pattern: ^ent_[A-Za-z0-9]+$
Example:

"ent_H0hdMOc5E5QMTEcGVZKegvLNCB6p"

​
payment_instructions
object[]
required
Minimum array length: 1

US ACH instructions

Response

Payment instructions created

​
object
enum<string>
required

Object type identifier.

Available options:
list
Example:

"list"

​
data
object[]
required

The page of items.

​
has_more
boolean
required

Whether there are more items available after this page.

​
url
string
required

The URL for this list endpoint.

Example:

"/v1/payment_instructions"