Withdrawals

The following endpoints are used to insert and retrieve entries representing withdrawals from the database.

WITHDRAWALS ENDPOINTS
WITHDRAWALS ENDPOINTS
POST /withdrawals
POST /withdrawals/:id/submit
GET /withdrawals/:id
GET /withdrawals

The withdrawal object

The withdrawal object represents a request for withdrawing fiat from the blockchain. You can create or retrieve an identityId's withdrawals via request to the API. Or, if you manage multiple identities in the network, you can also retrieve a list of withdrawals for all of them.

Withdrawals are identified by a unique, random id, and relate to a user's identityId.

WITHDRAWAL OBJECT
WITHDRAWAL OBJECT
{
"id": "2642dedd-4fa0-40bf-8b15-7c0513bcdb38",
"identityId": "e65dde2c-4379-42c7-a665-3f476cebb691",
"transactionReference": "0xf6cce2d20d2714fa7be8e1bb8b8cf0abbb12ca3d34d000073742a4da954c1be5",
"blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
"amount": null,
"currency": "USD",
"transactionHash": null,
"transferInformation": {
"transferType": "wire",
"bankAccountName": "Jonh do bank",
"bankAccountNumber": "1321312312321312",
"routingNumber": "123456789"
},
"status": "prepared",
"paymentDetails": null,
"transactionNumber": null,
"specialType": null,
"createdAt": "2020-02-19T11:43:04.553Z",
"updatedAt": "2020-02-19T11:43:04.553Z"
}

post
POST /withdrawals

[ENVIRONMENT HOSTNAME]/withdrawals
This endpoint allows you to add a new withdrawal to the database. If all the params are valid, a new record will be inserted in the database with the withdrawal information. This will return a transaction reference that needs to be provided to the transaction when performing the burn token action in the blockchain.
Request
Response
Request
Body Parameters
blockchainAddress
required
string
Address where the money will be withdrawn
currency
required
string
Currency of the funds to withdraw
identityId
required
string
Id of the identity associated to the request
transferInformation
required
object
Object containing the information of the transfer
Response
200: OK
{
"id": "2642dedd-4fa0-40bf-8b15-7c0513bcdb38",
"identityId": "e65dde2c-4379-42c7-a665-3f476cebb691",
"transactionReference": "0xf6cce2d20d2714fa7be8e1bb8b8cf0abbb12ca3d34d000073742a4da954c1be5",
"blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
"amount": null,
"currency": "USD",
"transactionHash": null,
"transferInformation": {
"transferType": "wire",
"bankAccountName": "Jonh do bank",
"bankAccountNumber": "1321312312321312",
"routingNumber": "123456789"
},
"status": "prepared",
"paymentDetails": null,
"transactionNumber": null,
"specialType": null,
"createdAt": "2020-02-19T11:43:04.553Z",
"updatedAt": "2020-02-19T11:43:04.553Z"
}
403: Forbidden
Response given when the identity is not yet approved.
{
"code": "identity_not_approved",
"status": 403
}

Example Call

Request
Curl
Response
Request
POST [ENVIRONMENT HOSTNAME]/withdrawals
{
"blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
"currency": "USD",
"identityId": "e65dde2c-4379-42c7-a665-3f476cebb691",
"transferInformation": {
"transferType": "wire",
"bankAccountName": "Jonh do bank",
"bankAccountNumber": "1321312312321312",
"routingNumber": "123456789"
}
}
Curl
curl -X POST \
[ENVIRONMENT HOSTNAME]/withdrawals \
-H 'Content-Type: application/json' \
-H 'apikey: {INSERT API KEY HERE}' \
-d '{
"blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
"currency": "USD",
"identityId": "e65dde2c-4379-42c7-a665-3f476cebb691",
"transferInformation": {
"transferType": "wire",
"bankAccountName": "Jonh do bank",
"bankAccountNumber": "1321312312321312",
"routingNumber": "123456789"
}
}'
Response
{
"id": "2642dedd-4fa0-40bf-8b15-7c0513bcdb38",
"identityId": "e65dde2c-4379-42c7-a665-3f476cebb691",
"transactionReference": "0xf6cce2d20d2714fa7be8e1bb8b8cf0abbb12ca3d34d000073742a4da954c1be5",
"blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
"amount": null,
"currency": "USD",
"transactionHash": null,
"transferInformation": {
"transferType": "wire",
"bankAccountName": "Jonh do bank",
"bankAccountNumber": "1321312312321312",
"routingNumber": "123456789"
},
"status": "prepared",
"paymentDetails": null,
"transactionNumber": null,
"specialType": null,
"createdAt": "2020-02-19T11:43:04.553Z",
"updatedAt": "2020-02-19T11:43:04.553Z"
}

On the Sandbox environment, you can use the settle withdrawal endpoint to simulate and settle the withdrawal request you created.

post
POST /withdrawals/:id/submit

[ENVIRONMENT HOSTNAME]/withdrawals/:id/submit
This method can be used to submit a withdrawal after the tokens were burned in the blockchain. This endpoint receives the transactionHash of the burn operation has a body parameter. This will be used to check if the transaction operation matches the data provided when creating the withdrawal request.
Request
Response
Request
Path Parameters
id
required
string
Withdrawal id to be submitted
Body Parameters
transactionHash
required
string
Transaction hash of the burn operation
Response
200: OK
{
"id": "37e2b53c-f938-4dce-90ef-7614f7e338f5",
"identityId": "80d82e03-527e-46ff-b5a2-6e5d7d34115c",
"transferType": "wire",
"transactionReference": "0x8722597478bb2ab2964576b9509941269642c2d960ac7bc452cd8cd5f9e64f2e",
"blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
"amount": "10",
"currency": "USD",
"transactionHash": "0xfa7102053dceb6cdc59b1580706a9fec7b14333d30d041ad4f03b0d8359f63c8",
"transferMethodId": null,
"status": "submitted",
"paymentDetails": null,
"transactionNumber": null,
"specialType": null,
"createdAt": "2020-02-19T17:20:35.948Z",
"updatedAt": "2020-02-19T17:23:21.068Z"
}

Example Call

Request
Curl
Response
Request
POST [ENVIRONMENT HOSTNAME]/withdrawals/37e2b53c-f938-4dce-90ef-7614f7e338f5/submit
Curl
curl --location --request POST 'localhost:3000/withdrawals/37e2b53c-f938-4dce-90ef-7614f7e338f5/submit' \
--header 'Content-Type: application/json' \
--header 'apikey: {{INSERT YOUR API KEY HERE}}' \
--data-raw '{
"transactionHash": "0xfa7102053dceb6cdc59b1580706a9fec7b14333d30d041ad4f03b0d8359f63c8"
}'
Response
{
"id": "37e2b53c-f938-4dce-90ef-7614f7e338f5",
"identityId": "80d82e03-527e-46ff-b5a2-6e5d7d34115c",
"transferType": "wire",
"transactionReference": "0x8722597478bb2ab2964576b9509941269642c2d960ac7bc452cd8cd5f9e64f2e",
"blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
"amount": "10",
"currency": "USD",
"transactionHash": "0xfa7102053dceb6cdc59b1580706a9fec7b14333d30d041ad4f03b0d8359f63c8",
"transferMethodId": null,
"status": "submitted",
"paymentDetails": null,
"transactionNumber": null,
"specialType": null,
"createdAt": "2020-02-19T17:20:35.948Z",
"updatedAt": "2020-02-19T17:23:21.068Z"
}

On the Sandbox environment, you can use the settle withdrawal endpoint to simulate and settle the withdrawal request you created.

get
GET /withdrawals/:id

[ENVIRONMENT HOSTNAME]/withdrawals/:id
This endpoint retrieves a single withdrawal that you've created by its specific id attribute.
Request
Response
Request
Path Parameters
id
required
string
Id of the withdrawal to be fetched
Response
200: OK
{
"id": "6f0c5931-326d-431a-87b8-5368dcdf6d61",
"identityId": "28961623-68b4-4fe3-bb16-9636eac5aab2",
"transferInformation": {
"transferType": "wire",
"bankAccountName": "Jonh do bank",
"bankAccountNumber": "1321312312321312",
"routingNumber": "123456789"
},
"transactionReference": "0xd570c59208bd0cd8b5f29d7df86015aa31e0c978e38b6695cf309e0bd77e2764",
"blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
"amount": null,
"currency": "USD",
"transactionHash": null,
"status": "prepared",
"paymentDetails": null,
"transactionNumber": null,
"specialType": null,
"createdAt": "2020-02-18T14:41:01.757Z",
"updatedAt": "2020-02-18T14:41:01.757Z"
}

Example Call

Request
Curl
Response
Request
GET [ENVIRONMENT HOSTNAME]/withdrawals/6f0c5931-326d-431a-87b8-5368dcdf6d61
Curl
curl -X GET \
[ENVIRONMENT HOSTNAME]/withdrawals/6f0c5931-326d-431a-87b8-5368dcdf6d61 \
-H 'apikey: {INSERT API KEY HERE}'
Response
{
"id": "6f0c5931-326d-431a-87b8-5368dcdf6d61",
"identityId": "28961623-68b4-4fe3-bb16-9636eac5aab2",
"transferInformation": {
"transferType": "wire",
"bankAccountName": "Jonh do bank",
"bankAccountNumber": "1321312312321312",
"routingNumber": "123456789"
},
"transactionReference": "0xd570c59208bd0cd8b5f29d7df86015aa31e0c978e38b6695cf309e0bd77e2764",
"blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
"amount": null,
"currency": "USD",
"transactionHash": null,
"status": "prepared",
"paymentDetails": null,
"transactionNumber": null,
"specialType": null,
"createdAt": "2020-02-18T14:41:01.757Z",
"updatedAt": "2020-02-18T14:41:01.757Z"
}

get
GET /withdrawals

[ENVIRONMENT HOSTNAME]/withdrawals/
This endpoint returns a list of all withdrawals submitted by you. This endpoint supports pagination.
Request
Response
Request
Response
200: OK
{
"total": 1,
"data": [
{
"id": "6f0c5931-326d-431a-87b8-5368dcdf6d61",
"identityId": "28961623-68b4-4fe3-bb16-9636eac5aab2",
"transferInformation": {
"transferType": "wire",
"bankAccountName": "Jonh do bank",
"bankAccountNumber": "1321312312321312",
"routingNumber": "123456789"
},
"transactionReference": "0xd570c59208bd0cd8b5f29d7df86015aa31e0c978e38b6695cf309e0bd77e2764",
"blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
"amount": null,
"currency": "USD",
"transactionHash": null,
"status": "prepared",
"paymentDetails": null,
"transactionNumber": null,
"specialType": null,
"createdAt": "2020-02-18T14:41:01.757Z",
"updatedAt": "2020-02-18T14:41:01.757Z"
}
]
}

Example call

Request
Curl
Response
Request
GET [ENVIRONMENT HOSTNAME]/withdrawals
// PAGINATED
GET [ENVIRONMENT HOSTNAME]/withdrawals?page[number]=1&page[size]=1
Curl
curl -X GET \
[ENVIRONMENT HOSTNAME]/withdrawals \
-H 'apikey: {INSERT API KEY HERE}'
Response
{
"total": 1,
"data": [
{
"id": "6f0c5931-326d-431a-87b8-5368dcdf6d61",
"identityId": "28961623-68b4-4fe3-bb16-9636eac5aab2",
"transferInformation": {
"transferType": "wire",
"bankAccountName": "Jonh do bank",
"bankAccountNumber": "1321312312321312",
"routingNumber": "123456789"
},
"transactionReference": "0xd570c59208bd0cd8b5f29d7df86015aa31e0c978e38b6695cf309e0bd77e2764",
"blockchainAddress": "0x8ba13aB181E9F30e543C6376Cd408192E95bCD1C",
"amount": null,
"currency": "USD",
"transactionHash": null,
"status": "prepared",
"paymentDetails": null,
"transactionNumber": null,
"specialType": null,
"createdAt": "2020-02-18T14:41:01.757Z",
"updatedAt": "2020-02-18T14:41:01.757Z"
}
]
}