How to withdraw funds

To be able to withdraw funds from an account, the account must be open, the account must have disbursements-frozen set to false, and have disbursable funds of the currency-type being disbursed. Once these criteria have been met funds can be withdrawn from an account via disbursements with a funds-transfer-method. The steps to make a disbursement out of an account is as follows.

  1. Create a funds-transfer-method of the desired outgoing funds-transfer-type. This can also be created in line with the disbursement.

  2. Create a disbursement with the appropriate funds-transfer-method.

Seen below is a disbursement made with a wire funds-transfer-method. Since a contact is specified the beneficiary-address will be assumed from the linked contact.

Note that a user provided reference can also be provided on the disbursement.

Request

POST v2/funds-transfer-methods?include=bank
{
"data" : {
"type" : "funds-transfer-methods",
"attributes" : {
"contact-id" : "{{contact-id}}",
"bank-account-name" : "John James Doe",
"bank-account-number" : "123456890",
"routing-number" : "123456789",
"funds-transfer-type" : "wire"
}
}
}

Response

{
"data": {
"type": "funds-transfer-methods",
"id": "4b4b265d-904e-4efc-8e2f-041f9468c391",
"attributes": {
"ach-check-type": null,
"bank-account-name": "John James Doe",
"bank-account-type": "checking",
"bank-name": null,
"check-payee": null,
"contact-email": "johndoe@email.in",
"contact-name": "John James Doe",
"credit-card-name": null,
"credit-card-postal-code": null,
"credit-card-type": null,
"credit-card-expiration-date": null,
"funds-transfer-type": "wire",
"further-credit-account-name": null,
"further-credit-account-number": null,
"iban": null,
"inactive": false,
"intermediary-bank-name": null,
"intermediary-bank-reference": null,
"ip-address": null,
"label": null,
"last-4": "6890",
"routing-number": "123456789",
"swift-code": null
},
"links": {
"self": "/v2/funds-transfer-methods/4b4b265d-904e-4efc-8e2f-041f9468c391"
},
"relationships": {
"aml-checks": {
"links": {
"related": "/v2/aml-checks?funds-transfer-method.id=4b4b265d-904e-4efc-8e2f-041f9468c391"
}
},
"contributions": {
"links": {
"related": "/v2/contributions?funds-transfer-method.id=4b4b265d-904e-4efc-8e2f-041f9468c391"
}
},
"disbursements": {
"links": {
"related": "/v2/disbursements?funds-transfer-method.id=4b4b265d-904e-4efc-8e2f-041f9468c391"
}
},
"funds-transfers": {
"links": {
"related": "/v2/funds-transfers?funds-transfer-method.id=4b4b265d-904e-4efc-8e2f-041f9468c391"
}
},
"bank": {
"data": {
"type": "banks",
"id": "5509d447-81aa-4da3-abea-0935ba310ef0"
}
},
"contact": {
"links": {
"related": "/v2/contacts/7ae9525b-4127-48e8-a089-80199b0383cd"
}
},
"credit-card-resource": {
"links": {
"related": "/v2/credit-card-resources/"
}
},
"plaid-item": {
"data": null
},
"bank-address": {
"data": null
},
"beneficiary-address": {
"links": {
"related": "/v2/funds-transfer-methods/4b4b265d-904e-4efc-8e2f-041f9468c391/beneficiary-address"
}
},
"intermediary-bank-address": {
"data": null
},
"mailing-address": {
"data": null
}
}
},
"included": [
{
"type": "banks",
"id": "5509d447-81aa-4da3-abea-0935ba310ef0",
"attributes": {
"name": "test",
"routing-number": "123456789",
"routing-number-type": "aba"
},
"links": {
"self": "/v2/banks/5509d447-81aa-4da3-abea-0935ba310ef0"
},
"relationships": {
"address": {
"links": {
"related": "/v2/banks/5509d447-81aa-4da3-abea-0935ba310ef0/address"
}
}
}
}
]
}

Make a withdrawal

Request

POST v2/disbursements?include=funds-transfer,disbursement-authorization
{
"data" : {
"type" : "disbursements",
"attributes" : {
"account-id" : "{{account-id}}",
"funds-transfer-method-id" : "{{funds-transfer-method-id}}",
"amount" : "1000",
"reference" : "MMXYZ123"
}
}
}

Response

{
"data": {
"type": "disbursements",
"id": "1e57b895-08ac-4760-8cbe-6aa996a7e402",
"attributes": {
"amount": 1000,
"created-at": "2019-12-03T23:15:01Z",
"description": null,
"customer-reference": "MMXYZ123",
"currency-type": "USD",
"payment-details": null,
"reference-number": null,
"special-type": null,
"status": "pending",
"transaction-number": null
},
"links": {
"self": "/v2/disbursements/1e57b895-08ac-4760-8cbe-6aa996a7e402"
},
"relationships": {
"account": {
"links": {
"related": "/v2/accounts/2053f64b-3631-4e64-a611-0bd09e687af6"
}
},
"contact": {
"links": {
"related": "/v2/contacts?funds-transfers.id=5168f675-b9a9-474c-8c2e-52a1c2fb0209&one"
}
},
"currency": {
"links": {
"related": "/v2/currencies/USD"
}
},
"disbursement-authorization": {
"data": {
"type": "disbursement-authorizations",
"id": "ee81f3b1-b746-4a28-87fe-e7bf85e1e9e9"
}
},
"funds-transfer": {
"data": {
"type": "funds-transfers",
"id": "5168f675-b9a9-474c-8c2e-52a1c2fb0209"
}
},
"funds-transfer-method": {
"links": {
"related": "/v2/funds-transfer-methods/cf91c5e7-aebf-4c48-a5e6-365a7e9c834d"
}
},
"payment-method": {
"links": {
"related": "/v2/payment-methods?funds-transfer.id=5168f675-b9a9-474c-8c2e-52a1c2fb0209&one"
}
}
}
},
"included": [
{
"type": "funds-transfers",
"id": "5168f675-b9a9-474c-8c2e-52a1c2fb0209",
"attributes": {
"amount": -1000,
"amount-expected": null,
"cancelled-at": null,
"clears-on": null,
"created-at": "2019-12-03T23:15:01Z",
"contingencies-cleared-on": null,
"currency-type": "USD",
"funds-source-name": null,
"funds-transfer-type": "ach",
"reference": "MMXYZ123",
"reversal-details": null,
"settlement-details": null,
"special-instructions": null,
"special-type": null,
"status": "pending"
},
"links": {
"self": "/v2/funds-transfers/5168f675-b9a9-474c-8c2e-52a1c2fb0209"
},
"relationships": {
"children": {
"links": {
"related": "/v2/funds-transfers?parent.id=5168f675-b9a9-474c-8c2e-52a1c2fb0209"
}
},
"contingent-holds": {
"links": {
"related": "/v2/contingent-holds?funds-transfer.id=5168f675-b9a9-474c-8c2e-52a1c2fb0209"
}
},
"currency": {
"links": {
"related": "/v2/currencies/USD"
}
},
"account": {
"links": {
"related": "/v2/accounts/2053f64b-3631-4e64-a611-0bd09e687af6"
}
},
"contact": {
"links": {
"related": "/v2/contacts/7ae9525b-4127-48e8-a089-80199b0383cd"
}
},
"contribution": {
"links": {
"related": "/v2/contributions?funds-transfer.id=5168f675-b9a9-474c-8c2e-52a1c2fb0209&one"
}
},
"disbursement": {
"links": {
"related": "/v2/disbursements?funds-transfer.id=5168f675-b9a9-474c-8c2e-52a1c2fb0209&one"
}
},
"disbursement-authorization": {
"data": {
"type": "disbursement-authorizations",
"id": "ee81f3b1-b746-4a28-87fe-e7bf85e1e9e9"
}
},
"funds-transfer-method": {
"links": {
"related": "/v2/funds-transfer-methods/cf91c5e7-aebf-4c48-a5e6-365a7e9c834d"
}
},
"parent": {
"data": null
},
"refund": {
"data": null
},
"reversed-cash-transaction": {
"data": null
},
"settled-cash-transaction": {
"data": null
},
"shortage-from-child": {
"data": null
},
"surplus-to-child": {
"data": null
}
}
},
{
"type": "disbursement-authorizations",
"id": "ee81f3b1-b746-4a28-87fe-e7bf85e1e9e9",
"attributes": {
"authorized-at": null,
"created-at": "2019-12-03T23:15:01Z",
"last-owner-verification-request-at": "2019-12-03T23:15:01Z",
"owner-verification-data": null,
"owner-verification-type": "email",
"owner-verified-at": null,
"status": "pending"
},
"links": {
"self": "/v2/disbursement-authorizations/ee81f3b1-b746-4a28-87fe-e7bf85e1e9e9"
},
"relationships": {
"account": {
"links": {
"related": "/v2/accounts/2053f64b-3631-4e64-a611-0bd09e687af6"
}
},
"disbursement": {
"links": {
"related": "/v2/disbursements?funds-transfer.id=5168f675-b9a9-474c-8c2e-52a1c2fb0209&one"
}
},
"asset-disbursement": {
"data": null
},
"funds-transfer": {
"data": {
"type": "funds-transfers",
"id": "5168f675-b9a9-474c-8c2e-52a1c2fb0209"
}
},
"asset-transfer": {
"data": null
}
}
}
]
}

Track a withdrawal

The lifecycle of the disbursement request should be tracked via the corresponding funds-transfer. An outgoing funds-transfer needs to be verified and authorized via the disbursement-authorization and all related contingent-holds also need to be cleared before the outgoing funds-transfer can be settled.

Request

GET v2/funds-transfers?filter[id eq]={{funds-transfer-outgoing-id}}&include=contingent-holds,disbursement-authorization

Response

{
"links": {
"self": "/v2/funds-transfers?filter%5Bid+eq%5D=5168f675-b9a9-474c-8c2e-52a1c2fb0209&include=contingent-holds%2Cdisbursement-authorization",
"first": "/v2/funds-transfers?filter%5Bid+eq%5D=5168f675-b9a9-474c-8c2e-52a1c2fb0209&include=contingent-holds%2Cdisbursement-authorization&page%5Bnumber%5D=1&page%5Bsize%5D=25"
},
"meta": {
"page-count": 1,
"resource-count": 2
},
"data": [
{
"type": "funds-transfers",
"id": "5168f675-b9a9-474c-8c2e-52a1c2fb0209",
"attributes": {
"amount": -1000.0,
"amount-expected": null,
"cancelled-at": null,
"clears-on": null,
"created-at": "2019-12-03T23:15:01Z",
"contingencies-cleared-on": null,
"currency-type": "USD",
"funds-source-name": null,
"funds-transfer-type": "ach",
"reference": "MMXYZ123",
"reversal-details": null,
"settlement-details": null,
"special-instructions": null,
"special-type": null,
"status": "pending"
},
"links": {
"self": "/v2/funds-transfers/5168f675-b9a9-474c-8c2e-52a1c2fb0209"
},
"relationships": {
"children": {
"links": {
"related": "/v2/funds-transfers?parent.id=5168f675-b9a9-474c-8c2e-52a1c2fb0209"
}
},
"contingent-holds": {
"data": [
{
"type": "contingent-holds",
"id": "2bb9ea60-b1c7-4fed-b773-42f29ddfaef3"
},
{
"type": "contingent-holds",
"id": "edd239fb-3ec9-446a-bd38-3263f4df8eb6"
}
]
},
"currency": {
"links": {
"related": "/v2/currencies/USD"
}
},
"account": {
"links": {
"related": "/v2/accounts/2053f64b-3631-4e64-a611-0bd09e687af6"
}
},
"contact": {
"links": {
"related": "/v2/contacts/7ae9525b-4127-48e8-a089-80199b0383cd"
}
},
"contribution": {
"links": {
"related": "/v2/contributions?funds-transfer.id=5168f675-b9a9-474c-8c2e-52a1c2fb0209&one"
}
},
"disbursement": {
"links": {
"related": "/v2/disbursements?funds-transfer.id=5168f675-b9a9-474c-8c2e-52a1c2fb0209&one"
}
},
"disbursement-authorization": {
"data": {
"type": "disbursement-authorizations",
"id": "ee81f3b1-b746-4a28-87fe-e7bf85e1e9e9"
}
},
"funds-transfer-method": {
"links": {
"related": "/v2/funds-transfer-methods/cf91c5e7-aebf-4c48-a5e6-365a7e9c834d"
}
},
"parent": {
"data": null
},
"refund": {
"data": null
},
"reversed-cash-transaction": {
"data": null
},
"settled-cash-transaction": {
"data": null
},
"shortage-from-child": {
"data": null
},
"surplus-to-child": {
"data": null
}
}
}
],
"included": [
{
"type": "contingent-holds",
"id": "2bb9ea60-b1c7-4fed-b773-42f29ddfaef3",
"attributes": {
"cleared-at": null,
"created-at": "2019-12-03T23:15:01Z",
"hold-type": "aml_check",
"message": null,
"status": "pending"
},
"links": {
"self": "/v2/contingent-holds/2bb9ea60-b1c7-4fed-b773-42f29ddfaef3"
},
"relationships": {
"account": {
"links": {
"related": "/v2/accounts/2053f64b-3631-4e64-a611-0bd09e687af6"
}
},
"funds-transfer": {
"links": {
"related": "/v2/funds-transfers/5168f675-b9a9-474c-8c2e-52a1c2fb0209"
}
},
"asset-transfer": {
"links": {
"related": "/v2/asset-transfers/"
}
}
}
},
{
"type": "contingent-holds",
"id": "edd239fb-3ec9-446a-bd38-3263f4df8eb6",
"attributes": {
"cleared-at": null,
"created-at": "2019-12-03T23:15:01Z",
"hold-type": "disbursement_authorization",
"message": null,
"status": "pending"
},
"links": {
"self": "/v2/contingent-holds/edd239fb-3ec9-446a-bd38-3263f4df8eb6"
},
"relationships": {
"account": {
"links": {
"related": "/v2/accounts/2053f64b-3631-4e64-a611-0bd09e687af6"
}
},
"funds-transfer": {
"links": {
"related": "/v2/funds-transfers/5168f675-b9a9-474c-8c2e-52a1c2fb0209"
}
},
"asset-transfer": {
"links": {
"related": "/v2/asset-transfers/"
}
}
}
},
{
"type": "disbursement-authorizations",
"id": "ee81f3b1-b746-4a28-87fe-e7bf85e1e9e9",
"attributes": {
"authorized-at": null,
"created-at": "2019-12-03T23:15:01Z",
"last-owner-verification-request-at": "2019-12-03T23:15:01Z",
"owner-verification-data": null,
"owner-verification-type": "email",
"owner-verified-at": null,
"status": "pending"
},
"links": {
"self": "/v2/disbursement-authorizations/ee81f3b1-b746-4a28-87fe-e7bf85e1e9e9"
},
"relationships": {
"account": {
"links": {
"related": "/v2/accounts/2053f64b-3631-4e64-a611-0bd09e687af6"
}
},
"disbursement": {
"links": {
"related": "/v2/disbursements?funds-transfer.id=5168f675-b9a9-474c-8c2e-52a1c2fb0209&one"
}
},
"asset-disbursement": {
"data": null
},
"funds-transfer": {
"links": {
"related": "/v2/funds-transfers/5168f675-b9a9-474c-8c2e-52a1c2fb0209"
}
},
"asset-transfer": {
"data": null
}
}
}
]
}

The disbursement-authorization is verified via a customizable email sent to the emails listed on contacts linked to the account with an account-role of owner. It can be cleared in sandbox as seen below. Generally authorization is automatic after the disbursement-authorization has been owner-verified but this depends on the account-policy, this can also be done in sandbox.

Request

{{env}}/v2/disbursement-authorizations/{{disbursement-authorization-id}}/sandbox/verify-owner

Response

{
"data": {
"type": "disbursement-authorizations",
"id": "ee81f3b1-b746-4a28-87fe-e7bf85e1e9e9",
"attributes": {
"authorized-at": "2019-12-03T23:33:23Z",
"created-at": "2019-12-03T23:15:01Z",
"last-owner-verification-request-at": "2019-12-03T23:15:01Z",
"owner-verification-data": {
"ip_address": "24.253.117.242",
"user_agent": "PostmanRuntime/7.19.0"
},
"owner-verification-type": "email",
"owner-verified-at": "2019-12-03T23:33:23Z",
"status": "authorized"
},
"links": {
"self": "/v2/disbursement-authorizations/ee81f3b1-b746-4a28-87fe-e7bf85e1e9e9"
},
"relationships": {
"account": {
"links": {
"related": "/v2/accounts/2053f64b-3631-4e64-a611-0bd09e687af6"
}
},
"disbursement": {
"links": {
"related": "/v2/disbursements?funds-transfer.id=5168f675-b9a9-474c-8c2e-52a1c2fb0209&one"
}
},
"asset-disbursement": {
"data": null
},
"funds-transfer": {
"links": {
"related": "/v2/funds-transfers/5168f675-b9a9-474c-8c2e-52a1c2fb0209"
}
},
"asset-transfer": {
"data": null
}
}
},
"included": []
}

Once the disbursement-authorization and the contingent-holds related to the outgoing funds-transfer are authorized and cleared respectively then the funds-transfer can be settled as seen below in sandbox. Once a funds-transfer settles a corresponding cash transaction will be created. If the funds-transfer is reversed due to return of the funds an offsetting cash-transaction will be created.

Request

POST v2/funds-transfers/{{funds-transfer-outgoing-id}}/sandbox/settle

Response

{
"data": {
"type": "funds-transfers",
"id": "5168f675-b9a9-474c-8c2e-52a1c2fb0209",
"attributes": {
"amount": -1000.0,
"amount-expected": null,
"cancelled-at": null,
"clears-on": null,
"created-at": "2019-12-03T23:15:01Z",
"contingencies-cleared-on": "2019-12-03",
"currency-type": "USD",
"funds-source-name": null,
"funds-transfer-type": "ach",
"reference": "MMXYZ123",
"reversal-details": null,
"settlement-details": "Settled via sandbox API",
"special-instructions": null,
"special-type": null,
"status": "settled"
},
"links": {
"self": "/v2/funds-transfers/5168f675-b9a9-474c-8c2e-52a1c2fb0209"
},
"relationships": {
"children": {
"links": {
"related": "/v2/funds-transfers?parent.id=5168f675-b9a9-474c-8c2e-52a1c2fb0209"
}
},
"contingent-holds": {
"links": {
"related": "/v2/contingent-holds?funds-transfer.id=5168f675-b9a9-474c-8c2e-52a1c2fb0209"
}
},
"currency": {
"links": {
"related": "/v2/currencies/USD"
}
},
"account": {
"links": {
"related": "/v2/accounts/2053f64b-3631-4e64-a611-0bd09e687af6"
}
},
"contact": {
"links": {
"related": "/v2/contacts/7ae9525b-4127-48e8-a089-80199b0383cd"
}
},
"contribution": {
"links": {
"related": "/v2/contributions?funds-transfer.id=5168f675-b9a9-474c-8c2e-52a1c2fb0209&one"
}
},
"disbursement": {
"links": {
"related": "/v2/disbursements?funds-transfer.id=5168f675-b9a9-474c-8c2e-52a1c2fb0209&one"
}
},
"disbursement-authorization": {
"links": {
"related": "/v2/disbursement-authorizations?funds-transfer.id=5168f675-b9a9-474c-8c2e-52a1c2fb0209&one"
}
},
"funds-transfer-method": {
"links": {
"related": "/v2/funds-transfer-methods/cf91c5e7-aebf-4c48-a5e6-365a7e9c834d"
}
},
"parent": {
"data": null
},
"refund": {
"data": null
},
"reversed-cash-transaction": {
"data": null
},
"settled-cash-transaction": {
"links": {
"related": "/v2/cash-transactions/f6998608-b031-4412-8bb6-63ecb5099e18"
}
},
"shortage-from-child": {
"data": null
},
"surplus-to-child": {
"data": null
}
}
},
"included": []
}

See also

  • Disbursements

  • Funds Transfer Methods

  • Disbursement Authorizations

  • Funds Transfers

  • Contingent Holds

  • Account Cash Totals

  • Cash Transactions

  • Refunds

Last updated on