Request a grant payout

post/grants

API Version

Requests the payout of the selected grant offer.

Endpoint destination URL

https://balanceplatform-api-test.adyen.com/btl/v3/grants

Header Parameters

Required

Optional

A unique identifier for the message with a maximum of 64 characters (we recommend a UUID).

Request Parameters

Required

Optional

An object containing the details of the receiving party of the grant. Setting either an accountHolderId, balanceAccountId, or both is required.

The identifier of the grant account used for the grant.

The identifier of the grant offer that has been selected and from which the grant details will be used.

Response parameters

After submitting a call, you receive a response message to inform you that your request was received and processed.

Depending on the HTTP status code of the response message, it is helpful to build some logic to handle any errors that a request or the system may return.

HTTP Responses

200 - OK
The request has succeeded.
amountobject
An object containing the amount of the grant, in minor units.
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
balancesobject
An object containing the details of the existing grant.
currencystring
The three-character ISO currency code.
feeinteger
Fee amount.
principalinteger
Principal amount.
totalinteger
Total amount. A sum of principal amount and fee amount.
counterpartyobject
An object containing the details of the receiving party of the grant. Setting either an accountHolderId, balanceAccountId, or both is required.
accountHolderIdstring
The identifier of the receiving account holder. The payout will default to the primary balance account of this account holder if no balanceAccountId is provided.
balanceAccountIdstring
The identifier of the balance account that belongs to the receiving account holder.
transferInstrumentIdstring
The identifier of the transfer instrument that belongs to the legal entity of the account holder.
feeobject
An object containing the fee currency and value, in minor units.
amountobject
An object containing the fee amount.
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
grantAccountIdstring
The identifier of the grant account used for the grant.
grantOfferIdstring
The identifier of the grant offer that has been selected and from which the grant details will be used.
idstring
The identifier of the grant reference.
repaymentobject
An object containing the details of the 30-day repayment threshold.
basisPointsinteger
The repayment that is deducted daily from incoming net volume, in basis points.
termobject
An object containing the details of the configuration for repayment term.
estimatedDaysinteger
The estimated term for repaying the grant, in days.
maximumDaysinteger
The maximum term for repaying the grant, in days. Only applies when contractType is loan.
thresholdobject
An object containing the details of the 30-day repayment threshold.
amountobject
The amount to be repaid on a 30-day basis.
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
statusstring
The current status of the grant. Possible values: Pending, Active, Repaid, WrittenOff, Failed, Revoked.
400 - Bad Request
A problem reading or understanding the request.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
401 - Unauthorized
Authentication required.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
403 - Forbidden
Insufficient permissions to process the request.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
404 - Not Found
The payment was not found
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
422 - Unprocessable Entity
A request validation error.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
500 - Internal Server Error
The server could not process the request.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.

Request a grant payout

HTTP Responses

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

422 - Unprocessable Entity

500 - Internal Server Error