Disbursements API Endpoints

Disbursements

This endpoint is used to transfer funds as follows:

From a program funding source to a consumer account (disbursementIn)
From a consumer account to a program funding source (disbursementOut)

For a disbursementIn and a disbursementOut to work, an account must be configured for the organization that will be the source of the funds. A fixed accountIdentifer will be assigned to these “Funding Source” accounts, and it will be required in all disbursement requests.

API Call Structure

POST /programs/{programCode}/transfers

Things to Remember

The POST /adjustments endpoint has replaced the POST /transfers endpoint for partner funded disbursements.
Therefore, POST /adjustments should be used for all new disbursement flows and integrations.
The POST /transfers endpoint should be used only for disbursements, if you have already integrated with it.
Automatic retries for Disbursements Out are enabled.

Request Bodies

Sample Request – Disbursement In:-
POST https://bospart/baas/v1/programs/yourprogram/transfers
{
   "transferIdentifier":“111bedee-de7f-4012-b647-fca0ffda23aa”,
   "transferType":"disbursementIn",
   "transferAuthorizationType":"execute",
   "partnerReferenceData":"Optional Partner Defined String",
   "initiator":“1117FD32-600A-4F4F-82F0-4940CC811111”,
   "transferRoute":{
      "transactionAmount":20,
      "sourceTransferEndpoint":{
         "transferEndpointType":"programFundingSource",
         "identifier":“1117FD32-600A-4F4F-82F0-4940CC811111”,
         "currency":"USD"
      },
      "targetTransferEndpoint":{
         "transferEndpointType":"account",
         "identifier":“111d697b-d01a-46d9-94f1-e7dd02111111”,
         "currency":"USD"
         }
   }
}

Sample Request – Disbursement Out:-
POST /programs/acme/transfers HTTP/1.1
{
   "transferIdentifier":“914f7ce8-8eab-4c8d-aad7-a96634583ae2”,
   "transferType":" disbursementOut",
   "transferAuthorizationType":"execute",
   "partnerReferenceData":"An optional string defined by the partner",
   "initiator":“05D81303-45A7-4859-87E2-FF75B49647DD”,
   "transferRoute":{
      "transactionAmount":10,
      "sourceTransferEndpoint":{
         "transferEndpointType":"account",
         "identifier":“05D81303-45A7-4859-87E2-FF75B49647DD”,
         "currency":"USD"
      },
      "targetTransferEndpoint":{
         "transferEndpointType":"programFundingSource",
         "identifier":“64888342-de79-4a61-8a39-909b2a7ebbb5”,
         "currency":"USD"
      }
   }
}

Request Parameters – Disbursements

Field	Description
transferIdentifier	If the transaction is initiated through the transfers API, then the transferIdentifier uniquely identifying the initiating transfer will be included.
transferType	Use either disbursementIn or disbursementOut to transfer funds between a Funding Source Account and a Consumer Account. • The disbursementIn transfer will be declined for the following account statuses: o Pending o Restricted: This constraint will be implemented in the 4/7/20 release. o Locked o Closed • The disbursementOut transfer will be declined for the following statuses: o Pending o Restricted: Except if the status reason is customerInitiatedSpendDown. o Locked o Closed
transferAuthorizationType	Only execute is valid for disbursement transfers at this time.
partnerReferenceData	Optional. When a valid disbursementIn or disbursementOut request is processed, the Partner has the option to provide information in the partnerReferenceData field that can be matched to the funding transfer request along with the corresponding transaction. Upon request, the partnerReferenceData can be included in the settlement report provided to the partner. Note: The purpose of the partnerReferenceData field being included in the request, is to allow you (the partner) the ability to cross reference the report information with your internal records.
Initiator	This is the account the transfer was initiated from. It must be either the source or the target account.
transferRoute	Contains the information for a POST Transfer call involving a new source and new target.
transactionAmount	The amount to transfer.
sourceTransferEndpoint	Represents the source of the funds.
transferEndpointType	Use programFundingSource for disbursementIn and account for disbursementOut.
identifier	The accountIdentifer of the applicable account based on the transferEndpointType.
currency	• If a currency code is provided in the request payload, then it must be a valid 3-character ISO code and be valid for the program for which the call is being made. • Currency is optional and will default to USD if not provided. • Only USD is supported for all programs.
targetTransferEndpoint	Represents the target of the funds.
transferEndpointType	Use account for disbursementIn or programFundingSource for disbursementOut.
Identifier	The accountIdentifer of the applicable account based on the transferEndpointType.
currency	Only USD is supported at this time.

Response Message

If the POST request is successful, the following response message will be returned along with a 201 HTTP status code.

New Transfer Created

Sample Response Body – Disbursement In & Disbursement Out

Note: Only the balance of the consumer account is returned in the response.

"responseDetails":[
   {
      "code":0,
      "subCode":0,
      "description":"Success",
      "url":"http://tbd"
   }
]
{
   "transfer":{
      "transferIdentifier":"111bedee-de7f-4012-b647-fca0ffda23aa",
      "transferStatus":"completed"
   },
   "accounts":[
      {
         "accountIdentifier":"111d697b-d01a-46d9-94f1-e7dd02111111",
         "purses":[
            {
               "purseIdentifier":"11111820-6f9b-4821-a848-cff108d11111",
               "purseType":"primary",
               "availableBalance":20.0,
               "ledgerBalance":20.0,
               "availableBalanceAsOfDateTime":"2019-07-30T14:56:12Z",
               "ledgerBalanceAsOfDateTime":"2019-07-30T14:56:12Z",
               "isHidden":false,
               "status":"0"
            }
         ]
      }
   ]

Response Parameters – Disbursement In & Disbursement Out

Field	Description
"responseDetails": [ { "code": 0, "subCode": 0, "description": "Success", "url": "http://tbd" }]	See Response Details for more information.
transfer	Contains the returned information in response to the POST /transfer call.
transferIdentifier	Unique identifier for the transfer.
transferStatus	Status of the transfer. Available status options are: • completed • pending • failed • canceled • declined • returned • rejected • expired
accounts	Contains the account information.
accountIdentifier	Unique identifier for an account within a program.
purses	A purse is a balance holding object. This returns all purses including the primary/checking purse.
purseIdentifier	Unique identifier for the purse that is returned.
purseType	Type of purse being returned.
availableBalance	The amount available on the account.
ledgerBalance	The amount of the ledger.
availableBalanceAsOfDateTime	The date and time (UTC) that the available balance is reflective of. Since events can be published out of chronological order, the available balance should not be updated, if a more recent available balance as of date was previously processed.
ledgerBalancesAsOfDateTime	The date and time (UTC) that the ledger balance is reflective of. Since events can be published out of chronological order, do not update the ledger balance if a more recent ledger balance as of date was previously processed.
isHidden	Allows the customer (user) to show or hide their purse on the mobile app.
status	N/A

Valid/Invalid Character Constraints

Note: Invalid characters are highlighted in bold. Anything outside the range in this table is also considered invalid.

Ascii	Character	Allowed in Partner Reference Data
32	space	Y
33	!	Y
34	"	Y
35	#	Y
36	$	Y
37	%	Y
38	&	Y
39	'	Y
40	(	Y
41	)	Y
42	*	Y
43	+	Y
44	,	N
45	-	Y
46	.	Y
47	/	Y
48	0	Y
49	1	Y
50	2	Y
51	3	Y
52	4	Y
53	5	Y
54	6	Y
55	7	Y
56	8	Y
57	9	Y
58	:	Y
59	;	N
60	<	Y
61	=	Y
62	>	Y
63	?	Y
64	@	Y
65	A	Y
66	B	Y
67	C	Y
68	D	Y
69	E	Y
70	F	Y
71	G	Y
72	H	Y
73	I	Y
74	J	Y
75	K	Y
76	L	Y
77	M	Y
78	N	Y
79	O	Y
80	P	Y
81	Q	Y
82	R	Y
83	S	Y
84	T	Y
85	U	Y
86	V	Y
87	W	Y
88	X	Y
89	Y	Y
90	Z	Y
91	[	Y
92	backslash Y	Y
93	]	Y
94	^	Y
95	_	Y
96	`	N
97	a	Y
98	b	Y
99	c	Y
100	d	Y
101	e	Y
102	f	Y
103	g	Y
104	h	Y
105	i	Y
106	j	Y
107	k	Y
108	l	Y
109	m	Y
110	n	Y
111	o	Y
112	p	Y
113	q	Y
114	r	Y
115	s	Y
116	t	Y
117	u	Y
118	v	Y
119	w	Y
120	x	Y
121	y	Y
122	z	Y
123	{	Y
124	\|	N
125	}	Y
126	~	Y

Retry Process

A retry process has been implemented for disbursementIn and disbursementOut transfer requests and reversals.

How it Works

If POST /transfers (disbursementIn and disbursementOut only) is called when a timeout with a downstream service has occurred, then:

The HTTP response to the partner will be 202 to indicate the Disbursement request is correctly pending retry
Transfer status is initially pending AND
The retry service will try to successfully complete the transaction every 30 minutes, for up to 24 hours.
If the transaction is not completed successfully after 24 hours, the transfer will be canceled. If an error occurs while the retry service is trying to cancel the transfer, then the transfer status will be marked as failed.
Note: When the transfer is in pending status due to a timeout AND the retry service fails to complete the transaction within 24 hours, then the status will be updated to canceled instead of failed.
A Webhook alert will be published

Transfer To/From Account under Same Partner Account (P2P)

This endpoints permits partners with multiple program codes to transfer money between accounts within those programs.

API Call Structure

POST /programs/{programCode}/transfers

How it Works

Simply call POST Transfers with the following information in your request: Refer to the Request Parameters table in the KYC API for details.

If the P2P request was put on hold then it needs to be executed, canceled or rejected. This is performed using the PUT /transfers API.

Call PUT programs/{programCode}/transfers/{transferIdentifier} to update the request to cancel, reject or execute, which will be reflected in the transferAuthorizationType.

Request Body

Sample Request Body:-
{
   "transferIdentifier":"d4ce622e-defa-4475-8d62-817c628b80e7",
   "transferType":"peerPayment",
   "transferAuthorizationType":"execute",
   "initiator":"0b830092-e5d4-45b8-ad26-8a42c94ddd4c",
   "memo":"string",
   "transferRoute":{
      "transactionAmount":5,
      "sourceTransferEndpoint":{
         "transferEndpointType":"account",
         "identifier":"0b830092-e5d4-45b8-ad26-8a42c94ddd4c",
         "currency":"USD"
      },
      "targetTransferEndpoint":{
         "transferEndpointType":"account",
         "identifier":"0b830092-e5d4-45b8-ad26-8a42c94ddd4c",
         "currency":"USD",
         "handleData":{
            "firstName":"string",
            "lastName":"string"
         }
      }
   }
}

Request Parameters

Field	Description
transferIdentifier	If the transaction is initiated through the transfers API, then the transferIdentifier uniquely identifying the initiating transfer will be included.
transferType	Type of transfer being done
transferAuthorizationType	Can be one of the following: •execute: Use if the recipient has auto-accept enabled. •hold: Use if the recipient prefers to manually accept.
initiator	Source of transfer
memo	An optional short description that is provided in the P2P message. Note: The memo can be retrieved via the GET /transfers by ID API. Details will be provided in the next sprint’s release notes (10/22).
transactionAmount	Amount of transaction excluding fees.
sourceTransferEndpoint	Contains information about the source of the transfer.
transferEndpointType	Type of endpoint the transfer is coming from (i.e. account).
identifier	Account identifier for the source account.
currency	Type of money being transferred (i.e. USD)
targetTransferEndpoint	Contains the encrypted data of the endpoint (account) that the transfer is going to.
transferEndpointType	Type of endpoint the transfer is going to (i.e. purse.
identifier	Account identifier for the target account.
currency	Type of money being accepted by the target account (i.e. USD). • If a currency code is provided in the request payload, then it must be a valid 3-character ISO code and be valid for the program for which the call is being made. • Currency is optional and will default to USD if not provided. • Only USD is supported for all programs.
handleData	Optional and is used in case the sender is identifying the recipient by a first and last name that may be different from the name on the recipient’s account.

Sample Response Body

Sample Response:-
{
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"string",
         "url":"string"
      }
   ],
   "transfer":{
      "transferIdentifier":"string",
      "transferStatus":"completed"
   },
   "accounts":[
      {
         "accountIdentifier":"0b830092-e5d4-45b8-ad26-8a42c94ddd4c",
         "purses":[
            {
               "purseIdentifier":"562a27ec-6cae-4459-a522-be94b4570f78",
               "purseType":"primary",
               "availableBalance":0,
               "ledgerBalance":0,
               "availableBalanceAsOfDateTime":"2019-09-13T17:49:33.932Z",
               "ledgerBalanceAsOfDateTime":"2019-09-13T17:49:33.932Z"
            }
         ]
      }
   ]
}

Response Parameters

Field	Description
"responseDetails": [ { "code": 0, "subCode": 0, "description": "Success", "url": "http://tbd" }]	See Response Details for more information.
transfer	Contains the returned information in response to the POST /transfer call.
transferIdentifier	Unique identifier for the transfer.
transferStatus	Status of the transfer. Available status options are: • completed • pending • failed • canceled • declined • returned • rejected • expired
accounts	Contains the account information.
accountIdentifier	Unique identifier for an account within a program.
purses	A purse is a balance holding object. This returns all purses including the primary/checking purse.
purseIdentifier	Unique identifier for the purse that is returned.
purseType	Type of purse being returned.
availableBalance	The amount available on the account.
ledgerBalance	The amount of the ledger.
availableBalanceAsOfDateTime	The date and time (UTC) that the available balance is reflective of. Since events can be published out of chronological order, the available balance should not be updated, if a more recent available balance as of date was previously processed.
ledgerBalancesAsOfDateTime	The date and time (UTC) that the ledger balance is reflective of. Since events can be published out of chronological order, do not update the ledger balance if a more recent ledger balance as of date was previously processed.

Sample Update Request

Sample Update Request:-
{
   "transferAuthorizationType":"execute"
}

Sample Update Response:-
{
   "responseDetails":[
      {
         "code":0,
         "subCode":0,
         "description":"string",
         "url":"string"
      }
   ],
   "transfer":{
      "transferStatus":"completed"
      }
}

Transfer from Business to Customer Card

This API performs a transfer from a business account to a customer card.

API Call Structure

POST /programs/{programCode}/transfers/singlecommit

Request Body

{  "transferRoute": {
    "transactionAmount": 0,
    "sourceTransferEndpoint": {
      "transferEndPointType": "string",
      "identifier": "string",
      "currency": "string",
      "encryptedCardData": {
        "version": "string",
        "ephemeralPublicKey": "string",
        "publicKeyHash": "string",
        "data": "string"
      },
      "encryptedBankAccount": {
        "version": "string",
        "ephemeralPublicKey": "string",
        "publicKeyHash": "string",
        "data": "string"
      },
      "encryptedUserData": {
        "version": "string",
        "ephemeralPublicKey": "string",
        "publicKeyHash": "string",
        "data": "string"
      }
    },
    "targetTransferEndpoint": {
      "transferEndPointType": "string",
      "identifier": "string",
      "currency": "string",
      "encryptedCardData": {
        "version": "string",
        "ephemeralPublicKey": "string",
        "publicKeyHash": "string",
        "data": "string"
      },
      "encryptedBankAccount": {
        "version": "string",
        "ephemeralPublicKey": "string",
        "publicKeyHash": "string",
        "data": "string"
      },
      "encryptedUserData": {
        "version": "string",
        "ephemeralPublicKey": "string",
        "publicKeyHash": "string",
        "data": "string"
      }
    }
  },
  "transferIdentifier": "string",
  "transferType": "string",
  "transferAuthorizationType": "string",
  "initiator": "string",
  "transferDescription": "string",
  "partnerReferenceData": "string"
}

Response Body

{
  "transfer": {
    "transferIdentifier": "string",
    "transferStatus": "string"
  },
  "accounts": [
    {
      "accountIdentifier": "string",
      "accountReferenceNumber": "string",
      "productCode": "string",
      "cipLevel": "string",
      "productMaterialType": "string",
      "currency": "string",
      "status": "string",
      "instantIssue": true,
      "statusReasons": [
        "string"
      ],
      "statusCure": "string",
      "accountStatusChangedDateTime": "string",
      "activationDate": "string",
      "directDepositInformation": {
        "accountNumber": "string",
        "routingNumber": "string"
      },
      "purses": [
        {
          "purseIdentifier": "string",
          "purseType": "string",
          "purseDescription": "string",
          "availableBalance": 0,
          "ledgerBalance": 0,
          "availableBalanceAsOfDateTime": "string",
          "ledgerBalanceAsOfDateTime": "string",
          "isHidden": true,
          "status": "string",
          "goalAmount": 0,
          "goalDate": "string",
          "iconName": "string",
          "createDate": "2023-01-29T22:59:31.772Z",
          "changeDate": "2023-01-29T22:59:31.772Z",
          "purseNumber": "string",
          "interestRateTierIdentifier": "string",
          "interestRateTier": "string",
          "interestYieldStartDate": "string",
          "interestYieldEndDate": "string",
          "APY": 0,
          "purseSubType": "string"
        }
      ],
      "additionalPurses": [
        {
          "purseIdentifier": "string",
          "purseType": "string",
          "purseDescription": "string",
          "availableBalance": 0,
          "ledgerBalance": 0,
          "availableBalanceAsOfDateTime": "string",
          "ledgerBalanceAsOfDateTime": "string",
          "isHidden": true,
          "status": "string",
          "goalAmount": 0,
          "goalDate": "string",
          "iconName": "string",
          "createDate": "2023-01-29T22:59:31.772Z",
          "changeDate": "2023-01-29T22:59:31.772Z",
          "purseNumber": "string",
          "interestRateTierIdentifier": "string",
          "interestRateTier": "string",
          "interestYieldStartDate": "string",
          "interestYieldEndDate": "string",
          "APY": 0,
          "purseSubType": "string"
        }
      ],
      "accountHolders": [
        {
          "paymentInstruments": [
            {
              "encryptedPrivatePaymentInstrumentData": {
                "version": "string",
                "ephemeralPublicKey": "string",
                "publicKeyHash": "string",
                "data": "string"
              },
              "privatePaymentInstrumentData": {
                "pan": "string",
                "cvv": "string",
                "expiration": {
                  "month": "string",
                  "year": "string"
                }
              },
              "paymentIdentifier": "string",
              "paymentInstrumentIdentifier": "string",
              "paymentInstrumentType": "string",
              "status": "string",
              "statusReasons": [
                "damaged"
              ],
              "isPinSet": true,
              "last4Pan": "string",
              "activatedDateTime": "string",
              "cardPausedDateTime": "string",
              "issuedDateTime": "string",
              "isOverIssuedDaysLimit": true,
              "isPrivateDataViewable": true,
              "embossedName": "string",
              "customCardImageIdentifier": "string",
              "paymentInstrumentLevel": "personalized"
            }
          ],
          "user": {
            "firstName": "string",
            "lastName": "string",
            "dobStatus": "string",
            "last4Identity": "string",
            "identityType": "string",
            "userIdentifier": "string",
            "peerTransferAcceptPreference": "string",
            "status": "string",
            "isPrimaryAccountHolder": true,
            "kycStateData": {
              "ofacStatus": "string",
              "kycStatus": "string",
              "kycPendingGate": "string"
            }
          },
          "accountHolderIdentifier": "string"
        }
      ],
      "termsAcceptances": [
        {
          "termsIdentifier": "string",
          "termsAcceptanceDateTime": "string",
          "termsAcceptanceFlag": true
        }
      ],
      "fraudData": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "accountType": "string",
      "language": "string",
      "accountCycleDay": 0,
      "accountEligibility": {
        "contactChangeEligibility": {
          "address": [
            "string"
          ],
          "email": [
            "string"
          ],
          "phone": [
            "string"
          ]
        }
      }
    }
  ],
  "fraudData": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "responseDetails": [
    {      "code": 0,
      "subCode": 0,
      "description": "string",
      "url": "string"
    }
  ]
}