Authorize Transaction
POST /transactions/authorize
Authorizes a Transaction request
Requires the use of an Authorization Bearer Token which is used to provide credentials that authenticate a user agent with a server, allowing access to a protected resource.
Request Body
custom_id
string
The custom identifier for this transaction.
Example value: 12345
type
string
REQUIRED
The transaction type.
Example value: PAYMENT
Possible Values
| Value | Description |
| PRENOTIFICATION | A notification sent in advance to inform a recipient about an upcoming transaction or payment |
| MICRODEPOSIT | A small deposit made to verify the accuracy of account details or to enable account activation. |
| PAYMENT | The act of transferring funds or value from one party to another as a settlement for goods or services. |
| REFUND | The return of funds or reimbursement to a customer, typically due to a cancellation, dissatisfaction, or overpayment. |
| PAYOUT | The distribution of funds or payment made to a recipient, often as a result of winnings, dividends, or earnings. |
| REVERSAL | The return of funds to a customer, typically due to a chargeback or dispute. |
| RETURN | The process of sending back goods or merchandise to the seller or provider, often resulting in a refund or exchange. |
| TRANSFER | The movement of funds or assets from one account, entity, or location to another, typically involving a change in ownership or control. |
tenant_id
string
The ID of the Tenant that originated the transaction.
Example value: ten_0521aadc-5fbd-4b3c-af0a-a4f4b8d6f20a
origin_account
string
REQUIRED
The transaction’s origin account details
Example value:
{
"token": "tok_e49f110e-804c-4e23-8e9c-4d4fae4c7868"
}
Attributes Definition
- uuid | string | The Id of the account used to fund this transaction.
- token | string | Token identifier
- institution_uuid | string | The UUID of the Institution where the Connected Account is registered.
- account_number | string | The account’s number.
- routing_number | string | The account’s routing number (usually indicates where the account was opened).
- existing_end_user_id | string | The UUID of an existing End User to associate with this Transaction.
- new_end_user_details | object
- type | string | The type of end user. Whether a company or an individual.
- first_name | string | The user’s first name.
- last_name | string | The user’s last name.
- organization | string | The organization’s name.
- organization_legal_name | string | The organization’s legal name.
- local_id | string | The user’s ID number.
- local_id_type | string | The user’s ID type.
- local_id_country | string | The user’s citizenship in 3-letter ISO code.
- email | string | The user’s email address.
- phone_number | object | The user’s phone number.
- country_code | string | The user’s phone number’s country code.
- number | string | The user’s phone number without country code.
The following fields are required based on the information passed through the object.
- institution_uuid IF uuid and token are not provided.
- account_number IF uuid and token are not provided.
- existing_end_user_id IF new_end_user_details is not present.
- new_end_user_details -> type IF new_end_user_details is present.
- new_end_user_details -> first_name IF type = INDIVIDUAL.
- new_end_user_details -> last_name IF type = INDIVIDUAL.
- new_end_user_details -> organization_legal_name IF type = ORGANIZATION
- new_end_user_details -> local_id IF country = COL.
- new_end_user_details -> local_id_type IF country = COL.
- new_end_user_details -> local_id_country IF country = COL
Attributes Example
"origin_account": {
"uuid": "acc_7985e8a4-8f38-4eab-8b27-a5d1c6dbf340",
"token": "tok_e49f110e-804c-4e23-8e9c-4d4fae4c7868",
"institution_uuid": "ins_ff6c5094-1cd1-11ec-9621-0242ac130002",
"account_number": 245532345,
"routing_number": 4432343,
"existing_end_user_id": "eur_7985e8a4-8f38-4eab-8b27-a5d1c6dbf341",
"new_end_user_details": {
"type": "INDIVIDUAL",
"first_name": "John",
"last_name": "Smith",
"organization": "DRUO",
"organization_legal_name": "DRUO Inc",
"local_id": 455235553,
"local_id_type": "NATIONAL_ID",
"local_id_country": "COL",
"email": "john.smith@druo.com",
"phone_number": {
"country_code": "1",
"number": 3053053000
}
}
}
destination_account
string
REQUIRED
The transaction’s destination account details
Example value:
{
"uuid": "acc_7985e8a4-8f38-4eab-8b27-a5d1c6dbf340"
}
Attributes Definition
- uuid | string | The Id of the account used to fund this transaction.
- token | string | Token identifier
- institution_uuid | string | The UUID of the Institution where the Connected Account is registered.
- account_number | string | The account’s number.
- routing_number | string | The account’s routing number (usually indicates where the account was opened).
- existing_end_user_id | string | The UUID of an existing End User to associate with this Transaction.
- new_end_user_details | object
- type | string | The type of end user. Whether a company or an individual.
- first_name | string | The user’s first name.
- last_name | string | The user’s last name.
- organization | string | The organization’s name.
- organization_legal_name | string | The organization’s legal name.
- local_id | string | The user’s ID number.
- local_id_type | string | The user’s ID type.
- local_id_country | string | The user’s citizenship in 3-letter ISO code.
- email | string | The user’s email address.
- phone_number | object | The user’s phone number.
- country_code | string | The user’s phone number’s country code.
- number | string | The user’s phone number without country code.
The following fields are required based on the information passed through the object.
- institution_uuid IF uuid and token are not provided.
- account_number IF uuid and token are not provided.
- existing_end_user_id IF new_end_user_details is not present.
- new_end_user_details -> type IF new_end_user_details is present.
- new_end_user_details -> first_name IF type = INDIVIDUAL.
- new_end_user_details -> last_name IF type = INDIVIDUAL.
- new_end_user_details -> organization_legal_name IF type = ORGANIZATION
- new_end_user_details -> local_id IF country = COL.
- new_end_user_details -> local_id_type IF country = COL.
- new_end_user_details -> local_id_country IF country = COL
Attributes Example
"destination_account": {
"uuid": "acc_7985e8a4-8f38-4eab-8b27-a5d1c6dbf340",
"token": "tok_e49f110e-804c-4e23-8e9c-4d4fae4c7868",
"institution_uuid": "ins_ff6c5094-1cd1-11ec-9621-0242ac130002",
"account_number": 245532345,
"routing_number": 4432343,
"existing_end_user_id": "eur_7985e8a4-8f38-4eab-8b27-a5d1c6dbf341",
"new_end_user_details": {
"type": "INDIVIDUAL",
"first_name": "John",
"last_name": "Smith",
"organization": "DRUO",
"organization_legal_name": "DRUO Inc",
"local_id": 455235553,
"local_id_type": "NATIONAL_ID",
"local_id_country": "COL",
"email": "john.smith@druo.com",
"phone_number": {
"country_code": "1",
"number": 3053053000
}
}
}
description
string
The description of this transaction. Users may see this description (e.g., in email receipts DRUO sends on your behalf).
Example value: Insurance policy renewal - INV12324
statement_descriptor
string
Description that DRUO will report to institutions so that it appears on your customers’ statements. This request may or may not be honored by the institutions. Must contain at least one letter, and be between 4 and 22 characters.
Example value: NOVO BILLING* INV12324
amount
integer
REQUIRED
The amount of money, in the smallest denomination of the currency indicated by currency, including the values after the decimal separator. For example, when currency is USD, amount is in cents. $10.00 USD is 1000.
Example value: 10000
currency
string
REQUIRED
The type of currency, in ISO 4217 format. See Currency for values. For example, the currency code for US dollars is USD.
Example value: USD
primary_reference
string
An optional primary ID you can associate with the transaction for your own purposes (such as to associate the transaction with an entity ID in your own database). This value cannot exceed 40 characters.
Example value: ABC123
secondary_reference
string
An optional secondary ID you can associate with the transaction for your own purposes (such as to associate the transaction with an entity ID in your own database). This value cannot exceed 40 characters.
Example value: bj39fhow39fhqp3f0hfae4344
metadata
string
Set of key-value pairs that you can attach to an object. You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.
Example value: {"order_id": "6735"}
auto_send_receipt
boolean
If true, the system should generate a receipt automatically to the preffered receipt method.
Example value: false
POST /transactions/authorize
curl --location 'https://api.druo.com/transactions/authorize' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--data '{
"type": "PAYMENT",
"origin_account": {
"token": "tok_e49f110e-804c-4e23-8e9c-4d4fae4c7868"
},
"destination_account": {
"uuid": "acc_7985e8a4-8f38-4eab-8b27-a5d1c6dbf340"
},
"amount": 100000,
"currency": "USD"
}'
Response Fields
uuid
string
The Transaction’s UUID.
Example value: trx_422f0f81-5001-4cce-a229-242d9ab9960a
code
string
The Transaction’s code.
Example value: TXNMW9PCWE
status
string
The Transaction’s status.
Example value: SUCCESSFUL
Other values: PROCESSING, SUCCESSFUL,
FAILED, CANCELED, REVERSED
type
string
The type of Transaction.
Example value: PAYMENT
tenant_id
string
The ID of the tenant used to in this transaction.
Example value:
ten_0521aadc-5fbd-4b3c-af0a-a4f4b8d6f20a
origin_account
object
The ID of the account used to fund this transaction.
Example value:
{"uuid": "acc_7985e8a4-8f38-4eab-8b27-a5d1c6dbf340"}
destination_account
object
The ID of the destination used in this transaction.
Example value:
{"uuid": "acc_7985e8a4-8f38-4eab-8b27-a5d1c6dbf340"}
total_amount
integer
The amount of money, in the smallest denomination of the currency indicated by currency, including the values after the decimal separator. For example, when currency is USD, amount is in cents. $10.00 USD is 1000.
Example value: 10000
total_fee
integer
The total fee amount charged for this transaction.
Example value: 400
net_amount
integer
The total net amount (total_amount minus total_fee) to be paid for this transaction
Example value: 9600
currency
object
The type of currency, in ISO 4217 format. See Currency for values. For example, the currency code for US dollars is USD.
Example value: {"code":"USD"}
description
string
The description of this transaction. Users may see this description (e.g., in email receipts DRUO sends on your behalf).
Example value: Insurance policy renewal - INV12324
statement_descriptor
string
Description that DRUO will report to institutions so that it appears on your customers’ statements. This request may or may not be honored by the institutions. Must contain at least one letter, and be between 4 and 22 characters.
Example value: NOVO BILLING* INV12324
primary_reference
string
An optional primary ID you can associate with the transaction for your own purposes (such as to associate the transaction with an entity ID in your own database). This value cannot exceed 40 characters.
Example value: ABC123
secondary_reference
string
An optional secondary ID you can associate with the transaction for your own purposes (such as to associate the transaction with an entity ID in your own database). This value cannot exceed 40 characters.
Example value: bj39fhow39fhqp3f0hfae4344
metadata
string
Set of key-value pairs that you can attach to an object. You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.
Example value: {"order_id": "6735"}
auto_send_receipt
boolean
If true, the system should generate a receipt automatically to the preffered receipt method
Example value: TRUE
date_created_gmt
string
Transaction created date
Example value: 2021-11-15T23:23:38
date_updated_gmt
string
Transaction updated date
Example value: 2021-11-15T23:23:38
Response
{
"uuid": "trx_422f0f81-5001-4cce-a229-242d9ab9960a",
"code": "TXNMW9PCWE",
"status": "SUCCEESSFUL",
"remarks": null,
"type": "PAYMENT",
"tenant_id": "ten_0521aadc-5fbd-4b3c-af0a-a4f4b8d6f20a",
"origin_account": {
"uuid": "acc_7985e8a4-8f38-4eab-8b27-a5d1c6dbf340"
},
"destination_account": {
"uuid": "acc_7985e8a4-8f38-4eab-8b27-a5d1c6dbf340"
},
"description": "Insurance policy renewal - INV12324",
"statement_descriptor": "NOVO BILLING* INV12324",
"amount": 10000,
"variable_fee": 300,
"fixed_fee": 100,
"total_fee": 400,
"net_amount": 9600,
"currency": {
"code": "USD"
},
"primary_reference": "ABC123",
"secondary_reference": "bj39fhow39fhqp3f0hfae4344",
"metadata": {
"order_id": "order-123123"
},
"auto_send_receipt": "TRUE",
"date_created_gmt": "2024-02-02T17:14:34.672Z",
"date_updated_gmt": "2024-02-02T17:14:34.672Z"
}