STstellar
Disbursements

Create Disbursement

Changed on

Creates a new disbursement in draft state with basic details. Important: a disbursement is not triggered until the organization adds receivers through the Upload Disbursement Instructions endpoint and the status changes from draft to ready .

post/disbursements

Request

  • Base URL
    (relative, and the document was published on a file host, not at the API’s origin)
  • Auth
    API key in header Authorization

Headers

X-Wallet-Idstring

Names the distribution account this request acts on. Required when the tenant has more than one active account. With a single active account, or an API key scoped to exactly one account, it may be omitted.

Request body */*

namestring
wallet_idstring
asset_idstring
verification_field'DATE_OF_BIRTH' | 'YEAR_MONTH' | 'PIN' | 'NATIONAL_ID_NUMBER'
registration_contact_type'EMAIL' | 'PHONE_NUMBER' | 'EMAIL_AND_WALLET_ADDRESS' | 'PHONE_NUMBER_AND_WALLET_ADDRESS'
receiver_registration_message_templatestring

Example request

{
  "name": "My New Disbursement name",
  "wallet_id": "e2de8544-b7e2-40a9-ad40-411f70d5c4bf",
  "asset_id": "d227a68c-2f40-11ee-be56-0242ac120002",
  "verification_field": "DATE_OF_BIRTH",
  "registration_contact_type": "PHONE_NUMBER",
  "receiver_registration_message_template": "You have a payment waiting for you from {{.OrganizationName}}. Click {{.RegistrationLink}} to register."
}

Response

A new disbursement

idstring

The unique identifier of the disbursement

namestring

The name of the disbursement

receiver_registration_message_templatestring

The custom template used to send invitations to receivers. The default message isn't returned. In the message's content it's possible to add the following template variables: {{.OrganizationName}} which is the Organization Name configured and {{.RegistrationLink}} which is the link generated by SDP to send to the receiver (in case this is not present in the message, it's automatically appended at the end).

registration_contact_type'EMAIL' | 'PHONE_NUMBER' | 'EMAIL_AND_WALLET_ADDRESS' | 'PHONE_NUMBER_AND_WALLET_ADDRESS'
status'DRAFT' | 'READY' | 'STARTED' | 'PAUSED' | 'COMPLETED' | 'CANCELED'
source_wallet_idstring

ID of the distribution account the disbursement is funded from.

verification_field'DATE_OF_BIRTH' | 'YEAR_MONTH' | 'PIN' | 'NATIONAL_ID_NUMBER'
file_namestring
created_atstring date-time
updated_atstring date-time
total_paymentsinteger

Total number of payments

total_payments_sentinteger

Total number of successful payments

total_payments_failedinteger

Total number of failed payments

total_payments_remaininginteger

Total number of remaining payments

amount_disbursedstring

The total amount disbursed so far

total_amountstring

The total amount to be disbursed

average_amountstring

The average amount per payment

Example response

{
  "id": "619da857-8725-4c58-933d-c120a458e0f5",
  "name": "Disbursement Name",
  "receiver_registration_message_template": "You have a payment waiting for you from {{.OrganizationName}}. Click {{.RegistrationLink}} to register.",
  "wallet": {
    "id": "5ada9ed5-455a-4782-a0ee-160767e0deb1",
    "name": "Vibrant Assist",
    "homepage": "https://vibrantapp.com",
    "sep_10_client_domain": "api-dev.vibrantapp.com",
    "deep_link_schema": "https://vibrantapp.com/sdp-dev",
    "created_at": "2023-07-31T20:50:45.648Z",
    "updated_at": "2023-07-31T20:50:45.648Z"
  },
  "asset": {
    "id": "ffaec4b3-46b0-4db4-a4c4-6c3508057705",
    "code": "USDC",
    "issuer": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5",
    "created_at": "2023-02-03T10:45:51Z",
    "updated_at": "2023-02-03T10:45:51Z",
    "deleted_at": "2023-06-03T10:55:51Z"
  },
  "source_wallet_id": "4c379f5e-09b5-4472-a286-b84e249a1512",
  "status_history": [
    {
      "user_id": "3f351b9e-ed0f-40fa-a314-14757b42dab1",
      "timestamp": "2023-02-03T10:45:51Z"
    }
  ],
  "file_name": "disbursement-feb-03-2023.csv",
  "created_at": "2023-02-03T10:45:51Z",
  "updated_at": "2023-02-03T10:45:51Z",
  "total_payments": 10,
  "total_payments_sent": 8,
  "total_payments_failed": 1,
  "total_payments_remaining": 1,
  "amount_disbursed": "800.00",
  "total_amount": "1000.00",
  "average_amount": "100.00"
}

Changes

  • 7588d8d2a3c7Revision changes
    • warning

      added the new CANCELED enum value to the response property for the response status

    • warning

      added the new CANCELED enum value to the // response property for the response status

    • info

      added the new optional header request parameter X-Wallet-Id

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

  • 2b94ab613474Revision changes
    • warning

      removed the request property

    • warning

      removed the optional property from the response with the status

    • warning

      added the new YEAR_MONTH enum value to the response property for the response status

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status