Create internal payment

post

https://api.sandbox.ibanq.com/v1/internal-payments

Moves funds in a single currency between two of the declared client's own accounts, or between the declared client and its parent or one of its sub-accounts in either direction. Two sub-accounts cannot move funds to each other. Between two entities each pays its own internal transfer fee: the debited entity's on top of the amount, the credited entity's out of what it receives. The transfer completes immediately when the debiting account has sufficient available balance; there is no approval stage. Retries with the same idempotencyKey and the same details return 200 with the original internal payment's id instead of creating a duplicate. 409 is returned for a key reused with different details, or a byte-identical resubmission under a new key without incrementing copyNumber.

Body Params

clientId

string

required

length ≥ 1

Required; must be a client this credential may act for and own the debiting or the crediting account

debitingAccountId

string

required

length ≥ 1

creditingAccountId

string

required

length ≥ 1

amount

int64

required

> 0

Minor units of the given currency; must be greater than 0

currency

string

required

length ≥ 1

reference

string

required

length between 0 and 140

internalReference

string | null

copyNumber

int32

≥ 1

Deliberate-copy escape hatch: an otherwise byte-identical resubmission under a new idempotencyKey is rejected as a 409 duplicate unless copyNumber is incremented to signal a deliberate copy. Defaults to 1; must be 1 or greater

idempotencyKey

string

required

length between 0 and 100

Caller-generated key that makes the request retry-safe; at most 100 characters. Retrying with the same key and the same details returns 200 with the original internal payment's id, so a caller whose create response was lost can recover it by retrying. Reusing a key with different details is rejected with 409 whose body carries existingInternalPaymentId

Headers

DPoP

string

required

Fresh RFC 9449 proof JWT (ES256) signed with the client's DPoP key, binding this request's method and URL to the access token; generate a new proof per request

Content-Digest

string

required

RFC 9530 digest of the request body, e.g. sha-256=:...:

Signature-Input

string

required

RFC 9421 signature parameters: covered components plus created and keyid

Signature

string

required

RFC 9421 signature over the signature base, signed with the client's registered signing key

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

200Identical retry replayed; the id of the internal payment originally created under this idempotencyKey is returned

201Internal payment created; its id is returned. There is no Location header and no read-by-id endpoint — find it again through GET /internal-payments

400Invalid request parameters, or request signature verification failed

401Missing or invalid access token / DPoP proof

403Payments are not enabled for this client, or clientId does not match a client this credential may act for

404Client or account not found

409The idempotency key was reused with different transfer details, or this transfer is a duplicate of an existing one; existingInternalPaymentId identifies the internal payment already created under the supplied idempotencyKey, when there is one

422Business rule validation failed

500Internal server error

504The request timed out before a response could be produced.