Skip to main content

Introduction

The Xflow API is based on REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

To launch successfully with Xflow, you’ll need to integrate both systems and business processes with Xflow, plan for your launch and communicate with your stakeholders. We've written up helpful integration guides for both direct users (who are looking to accept funds for themselves) and platform users (who are looking to accept funds on behalf of other connected users). These guides provide you with tools and knowledge to help you launch your Xflow implementation.

You can also use the Xflow API in test mode. Test mode does not affect your live data or interact with the financial networks. The API key you use to authenticate the request determines whether the request is in live or test mode.

The Xflow API is also available on Postman. Feel free to fork a collection by visiting the Xflow Developers Workspace. In addition, our latest Open API spec is also available publicly on Github.

Base URL
https://api.xflowpay.com
Client Libraries
Coming Soon...

Authentication

The Xflow API uses API keys to authenticate requests. You can view and manage your API keys in the Xflow Dashboard.

Testmode secret keys have the prefix sk_test_ and livemode secret keys have the prefix sk_live_. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Bearer sk_test_your_key" instead of -u sk_test_your_key.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Authenticated Request
curl -L -X GET 'https://api.xflowpay.com/v1/receivables/receivable_f0A_1666079293438_eDQAH_000' \
-H 'Authorization: Bearer sk_your_key'

Errors

Xflow uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a payment failed, etc.). Codes in the 5xx range indicate an error with Xflow’s servers (these are rare).

You can find Xflow's error codes here.

Parameters
errorsarray of hashes

An array of errors. Each element is a specific error.

Child Parameters
http_status_codeinteger

HTTP status code.

objectstring

String representing the object’s type. Objects of the same type share the same value.

HTTP status code summary
400 - 200 - OK
Everything worked as expected.
400 - 400 - Bad Request
The request was unacceptable, often due to missing a required parameter.
400 - 401 - Unauthorized
No valid API key provided.
400 - 402 - Request Failed
The parameters were valid but the request failed.
400 - 403 - Forbidden
The API key doesn't have permissions to perform the request.
400 - 404 - Not Found
The requested resource doesn't exist.
400 - 409 - Conflict
The request conflicts with another request.
400 - 500, 502, 503, 504 - Server Errors
Something went wrong on Xflow's end - these are rare!
The error object
{
"errors": [
{
"code": "parameter_invalid_empty",
"message": "You did not provide a value for account.type. Please try again with a keyed-in enum value.",
"metadata": {
"field_name": "account.type"
}
}
],
"http_status_code": 400,
"object": "error"
}

Metadata

Updateable Xflow objects including accounts, files and receivables have a metadata parameter. You can use this parameter to attach key-value data to these objects. You can specify up to 10 keys, with key names up to 40 characters long and values up to 500 characters long.

Metadata is useful for storing additional, structured information on an object. As an example, you could store your user's full name and corresponding unique identifier from your system on an Xflow receivables object. Metadata is not used by Xflow, for example, Xflow does not use metadata to fail a payment and won't be seen by your users unless you choose to show it to them.

Do not store any sensitive information (bank account numbers, etc.) as metadata.

Request
curl -L -X POST 'https://api.xflowpay.com/v1/receivables/receivable_f0A_1666079293438_eDQAH_000' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"amount_maximum_reconcilable": "45.00",
"description": "This is a useful description",
"metadata": {
"internal_reference": "ABC-1234"
}
}'
Response
{
"account_id": "account_F0A_1666079163481_A7fje_000",
"amount_locked": "0.00",
"amount_maximum_reconcilable": "45.00",
"amount_reconcilable": "30.00",
"amount_settled_payouts": "19.95",
"created": 1666079293,
"currency": "USD",
"deposit_ids_amount_locked": [],
"description": "This is a useful description",
"id": "receivable_f0A_1666079293438_eDQAH_000",
"invoice": {
"amount": "50.00",
"creation_date": "2022-10-08",
"currency": "USD",
"document": "file_F0A_1666079283600_ffoLd_000",
"due_date": "2022-11-07",
"reference_number": "Invoice FY 2022-23-038"
},
"livemode": true,
"metadata": {
"internal_reference": "ABC-1234"
},
"object": "receivable",
"purpose_code": "P1006",
"purpose_code_description": "Business and management consultancy and public relations services",
"status": "activated",
"system_message": [],
"transaction_type": "services"
}

Pagination

All core API resources have support for bulk fetches via "list" API methods. For instance, you can list accounts, files and receivables. These list API methods share a common structure and support least 2 parameters: limit and starting_after. The objects returned as part of a list query are sorted in descending order on the created field, unless otherwise noted.

Parameters
dataarray of objects

An array containing the actual response elements, paginated by any request parameters.

ending_beforestringoptional

A cursor for use in pagination. ending_before is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

limitintegeroptional

A limit on the number of objects to be returned, between 1 and 10. If this parameter is not specified, a default value of 10 is assumed.

starting_afterstringoptional

A cursor for use in pagination. starting_after is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, ending with obj_bar, your subsequent call can include starting_after=obj_bar in order to fetch the next page of the list.


Pagination list response
dataarray of objects

An array containing the actual response elements, paginated by any request parameters.

has_nextboolean

Whether or not there are more elements available after this set. If false, this set comprises the end of the list.

objectstring

String representing the object’s type. Objects of the same type share the same value.

Response
{
"data": [
{
"bank_account": {
"domestic_credit": "CITI0000004",
"domestic_debit": null,
"domestic_fast_credit": null,
"domestic_wire": null,
"global_wire": null,
"iban": null,
"last4": "9007",
"number": "9874139007"
},
"billing_details": {
"city": "Bangalore",
"country": "IN",
"line1": "MG Road",
"line2": null,
"postal_code": "560038",
"state": null
},
"category": "user_payout",
"created": 1666160723,
"currency": "INR",
"id": "address_f0A_1666160723235_fJSRH_000",
"is_reusable": false,
"linked_id": "account_F0A_1666077553446_41Hgq_000",
"linked_object": "account",
"livemode": true,
"metadata": null,
"name": "address-name-1",
"object": "address",
"status": "activated",
"type": "bank_account"
},
{...},
{...}
],
"has_next": false,
"object": "list"
}

Accounts

Account objects are fundamental to Xflow and model entities like direct users, connected users, partners and platforms. Depending on whether you are setup as a direct user or platform, you can create new accounts, retrieve existing accounts to see its properties or take action on accounts to accept funds on their behalf.

The Account object

type: platform
Parameters
addressenum

This parameter represents the state of the xflow_receive addresses associated with this account. The valid values include deactivated, requested, processing and activated.

business_detailshash

Details about the business and activities that the account engages in.

Child Parameters
createdtimestamp

The seconds elapsed since Unix epoch time at which the account was created.

idstring

Unique identifier for the object.

Not applicable.

livemodeboolean

Has the value true if the object exists in livemode, the value false if the object exists in testmode or null in the case of a direct user or a platform (a direct user is an Xflow account of type=user which is not connected to an account of type=platform).

logo_idstring

A file object identifier which contains a logo for the user to customize communications with their customers.

metadatamap

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them.

nicknamestring

Name for the account.

objectstring

String representing the object’s type. Objects of the same type share the same value.

parent_account_idstring

Not applicable.

supporting_documentationhash

Details of the supporting documentation for the account.

Child Parameters
statusenum

draft Account has been created but not yet submitted for activation.

verifying Account activation request submitted and is being verified by Xflow.

activated Account is activated, can create live receivables and receive payouts.

deactivated Account is deactivated, cannot create live receivables or receive payouts.

hold Account is being held due to verification process outcome, please reach out to the Xflow Operations team.

tos_acceptancehash

Details of account accepting terms of service (tos).

Child Parameters
typeenum

platform is an account which is created by Xflow and has access to all of Xflow's capabilities including the ability to create its own users and partners.

The Account object
{
"address": "deactivated",
"business_details": {
"dba": "Xflow",
"email": "ops@xflow.com",
"ids": {
"business": "U11100KA2021FTC149048",
"tax": "AFBPB8047Q",
"tax_deduction": "BLRX00710A",
"tax_gst": "29AAACX3717G777",
"tax_trade": "YYZCX3717B"
},
"legal_name": "XFLOW PAYMENTS INDIA PRIVATE LIMITED",
"physical_address": {
"city": "Bangalore",
"country": "IN",
"line1": "No. 843, 2nd Floor, 5th Main Road",
"line2": "Indira Nagar 1st Stage,",
"postal_code": "560038",
"state": "Karnataka"
},
"product_description": "Cross-border payments infrastructure company",
"type": "company",
"website": "https://xflowpay.com"
},
"created": 1666077553,
"id": "account_F0A_1666077553446_41Hgq_000",
"link": null,
"livemode": null,
"logo_id": "file_F0A_1666077980329_rsfl3_000",
"metadata": null,
"nickname": null,
"object": "account",
"parent_account_id": null,
"supporting_documentation": {
"id_document": "file_F0A_1666078140654_lQm8l_000"
},
"status": "activated",
"tos_acceptance": {
"ip": "219.65.110.90",
"time": 1666078213,
"user_agent": "grpc-node-js/1.6.7"
},
"type": "platform"
}

Create an Account

type: partnerbusiness_details.type: company
Parameters
business_detailshashrequired

Details about the business and activities that the account engages in.

Child Parameters
metadatamapoptional

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them.

nicknamestringrequired

Unique name for the account.

typeenumrequired

Set to partner.

POST /v1/accounts
curl -L -X POST 'https://api.xflowpay.com/v1/accounts' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"business_details": {
"email": "Rene9@gmail.com",
"legal_name": "Macejkovic - Casper",
"physical_address": {
"city": "Bowling Green",
"country": "US",
"line1": "73427 Carmine Greens",
"postal_code": "94107",
"state": "CA"
},
"type": "company"
},
"nickname": "Jaime Howe",
"type": "partner"
}'

Retrieve an Account

Parameters
No parameters required.
GET /v1/accounts/:id
curl -L -X GET 'https://api.xflowpay.com/v1/accounts/account_F0A_1666184956871_JsBZ2_000' \
-H 'Authorization: Bearer sk_your_key'

Update an Account

type: user (connected)status: draft
Parameters
business_detailshashoptional

Details about the business and activities that the account engages in.

Child Parameters
logo_idstringoptional

A file object identifier which contains a logo for the user to customize communications with their customers.

metadatamapoptional

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them.

nicknamestringoptional

Name for the account.

supporting_documentationhashoptional

Details of the supporting documentation for the account.

Child Parameters
tos_acceptancehashoptional

Details of account accepting terms of service (tos).

Child Parameters
POST /v1/accounts/:id
curl -L -X POST 'https://api.xflowpay.com/v1/accounts/account_F0A_1689699873811_mK7SU_000' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"business_details": {
"email": "alternate_contact@shoedog.com"
},
"metadata": {
"internal_name": "Shoe and Sock Power"
}
}'

List all Accounts

This endpoint returns all accounts (filtered by the applied below query parameters) associated with the platform, connected user or direct user in question. Specifically, in context of a:

  • Platform, this endpoint will return the platform and its connected users
  • Connected user, this endpoint will return the connected user and its partners
  • Direct user, this endpoint will return the direct user and its partners

Parameters
addressarray of enumsoptional

This parameter represents the state of the xflow_receive addresses associated with this account. The valid values include deactivated, requested, processing and activated.

created.eqtimestampoptional

Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.

created.gttimestampoptional

Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.

created.gtetimestampoptional

Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.

created.lttimestampoptional

Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.

created.ltetimestampoptional

Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.

ending_beforestringoptional

A cursor for use in pagination. ending_before is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

limitintegeroptional

A limit on the number of objects to be returned, between 1 and 10. If this parameter is not specified, a default value of 10 is assumed.

starting_afterstringoptional

A cursor for use in pagination. starting_after is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, ending with obj_bar, your subsequent call can include starting_after=obj_bar in order to fetch the next page of the list.

statusarray of enumsoptional

draft Account has been created but not yet submitted for activation.

verifying Account activation request submitted and is being verified by Xflow.

activated Account is activated, can create live receivables and receive payouts.

deactivated Account is deactivated, cannot create live receivables or receive payouts.

hold Account is being held due to verification process outcome, please reach out to the Xflow Operations team.

typearray of enumsoptional

You can list accounts of type partner, platform or user.

GET /v1/accounts
curl -L -X GET 'https://api.xflowpay.com/v1/accounts?type=partner' \
-H 'Authorization: Bearer sk_your_key'

Activate an Account

Activating an account in Xflow enables real-world (aka as livemode within Xflow) money movement against it. There are three types of accounts in Xflow and activation for each of them is different.

1. Activate platform and direct user

Platforms and direct users can be activated only through the Xflow Dashboard.

2. Activate connected user

A connected user can be activated only by a platform over the API and the Xflow Dashboard. The activation will require the following:

  • Account object of type=user created by the platform
  • Address object of type=user_payout created by the platform on behalf of the connected user
  • Person objects for a director, owner and business representative created by the platform on behalf of the connected user

In addition, please remember the following:

  1. For business_details.type = company and limited_liability_partnership, a Company Identification Number (CIN) / LLP ID or Business PAN or GSTIN is required.
  • GSTIN can be passed in business_details.tax_gst. Alternatively, the user can pass a scanned copy of the GSTIN certificate as a file identifier in supporting_documentation.id_document. Remember to set the purpose for the file identifier to tax_document
  • CIN or LLP ID is passed in business_details.ids.business. Alternatively, the user can pass the Certificate of Incorporation as a file identifier in supporting_documentation.id_document. Remember to set the purpose for the file identifier to additional_verification
  • Business PAN is passed in business_details.ids.tax. Alternatively, the user can pass a scanned copy of the Business PAN as a file identifier in supporting_documentation.id_document. Remember to set the purpose for the file identifier to identity_document
  1. For business_details.type = sole_proprietor and individual, a GSTIN or Address is required.
  • GSTIN can be passed in business_details.tax_gst. Alternatively, the user can pass a scanned copy of the GSTIN certificate as a file identifier in supporting_documentation.id_document. Remember to set the purpose for the file identifier to tax_document
  • The physical address details will have to be provided in business_details.physical_address hash
  1. For business_details.type = partnership, a GSTIN is required.
  • GSTIN can be passed in business_details.tax_gst. In addition, the user must pass a scanned copy of the Partnership Deed as a file identifier in supporting_documentation.id_document. Remember to set the purpose for the file identifier to identity_document
  1. You can create a person by providing the image of the individual PAN card or individual PAN number (text) + full name. Please remember that for account.business_details.type:
  • company, limited_liability_partnership and partnership: for person of relationship owner alone, you can alternatively pass an image of their passport (this is to support non-Indian owners who may not have a PAN) or of course a PAN if one is available
  • sole_proprietor and individual: person.relationship.owner must be set to true and no other relationships are possible

Once the above setup is complete, you can proceed forward to activate the connected user.

3. Activate partner

A partner can be activated by a platform or a direct user over the API and the Xflow Dashboard.

Parameters
No parameters required.
POST /v1/accounts/:id/activate
curl -L -X POST 'https://api.xflowpay.com/v1/accounts/account_F0A_1666184956871_JsBZ2_000/activate' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json'

Deactivate an Account

You can only deactivate an account of type=partner.

Parameters
No parameters required.
POST /v1/accounts/:id/deactivate
curl -L -X POST 'https://api.xflowpay.com/v1/accounts/account_F0A_1666184956871_JsBZ2_000/deactivate' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json'

AccountSettings

The AccountSetting object models the settings for a given account. The AccountSetting object is created by Xflow at the time of account creation.

The AccountSetting object

type: platform
Parameters
account_idstring

This parameter represents the account object with which the AccountSetting object is associated.

addresshash

Default values for address of category xflow_receive availability for different types of accounts.

Child Parameters
address_currencyhash

Default values for the currency for address of category xflow_receive for different types of accounts.

Child Parameters
createdtimestamp

The seconds elapsed since Unix epoch time at which the AccountSetting was created.

idstring

Unique identifier for the object.

live_fxboolean

Indicates whether live FX is enabled for a platform's connected users. If true, payouts are processed immediately for all connected users.

livemodeboolean

Has the value true if the object exists in live mode or the value false if the object exists in test mode.

metadatamap

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them.

objectstring

String representing the object’s type. Objects of the same type share the same value.

payoutshash

Payouts details.

Child Parameters
The AccountSetting object
{
"account_id": "account_F0A_1666079993446_77Hgq_000",
"address": {
"connected_user": false,
"connected_user_partner": false,
"partner": false,
"platform": true,
"user": null
},
"address_currency": {
"connected_user": ["USD"],
"connected_user_partner": ["USD"],
"partner": ["USD"],
"platform": ["USD"],
"user": []
},
"created": 1666077553,
"id": "account_setting_F0A_1666077553446_41Hgq_000",
"live_fx": true,
"livemode": true,
"metadata": null,
"object": "account_setting",
"payouts": {
"enabled": true,
"interval": "monthly",
"monthly_anchor": 25,
"reason_code_not_enabled": "account_not_activated",
"weekly_anchor": null
}
}

Retrieve an AccountSetting

Parameters
No parameters required.
GET /v1/account_settings/:id
curl -L -X GET 'https://api.xflowpay.com/v1/account_settings/account_setting_F0A_1666184956871_JsBZ2_000' \
-H 'Authorization: Bearer sk_your_key'

Update an AccountSetting

type: user (connected)status: draft
Parameters
addresshashoptional

Default values for address of category xflow_receive availability for different types of accounts.

Child Parameters
address_currencyhashoptional

Default values for address of category xflow_receive availability for different types of accounts.

Child Parameters
metadatamapoptional

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them.

payoutshashoptional

Payouts details.

Child Parameters
POST /v1/account_settings/:id
curl -L -X POST 'https://api.xflowpay.com/v1/account_settings/account_setting_F0A_1689699873811_mK7SU_000' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"metadata": {
"internal_name": "Shoe and Sock Power"
}
}'

List all AccountSettings

This endpoint returns all AccountSettings (filtered by the applied below query parameters) associated with the platform, connected user or direct user in question. Specifically, in context of a:

  • Platform, this endpoint will return the platform and its connected users AccountSettings
  • Connected user, this endpoint will return the connected user and its partners AccountSettings
  • Direct user, this endpoint will return the direct user and its partners AccountSettings

Parameters
account_idarray of stringsoptional

This parameter represents the account object with which the AccountSetting object is associated.

address.connected_userbooleanoptional

Indicates whether an address is available by default for a connected user.

address.connected_user_partnerbooleanoptional

Indicates whether an address is available by default for a connected user's partner.

address.partnerbooleanoptional

Indicates whether an address is available by default for a partner.

address.platformbooleanoptional

Indicates whether an address is available by default for a platform.

address.userbooleanoptional

Indicates whether an address is available by default for a user.

created.eqtimestampoptional

Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.

created.gttimestampoptional

Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.

created.gtetimestampoptional

Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.

created.lttimestampoptional

Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.

created.ltetimestampoptional

Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.

ending_beforestringoptional

A cursor for use in pagination. ending_before is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

limitintegeroptional

A limit on the number of objects to be returned, between 1 and 10. If this parameter is not specified, a default value of 10 is assumed.

payouts.enabledbooleanoptional

Whether Xflow can send payouts to this account. This parameter can be set by Xflow for a direct user or by the platform on behalf of a connected user. The former is an Xflow account of type=user which is not connected to an account of type=platform.

payouts.reason_code_not_enabledarray of stringsoptional

account_not_activated Payouts are not enabled on this account as it has not been activated.

platform_hold Payouts are not enabled on this account as they have been disabled by the platform.

xflow_hold Payouts are not enabled on this account as they have been disabled by Xflow.

starting_afterstringoptional

A cursor for use in pagination. starting_after is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, ending with obj_bar, your subsequent call can include starting_after=obj_bar in order to fetch the next page of the list.

GET /v1/account_settings
curl -L -X GET 'https://api.xflowpay.com/v1/account_settings?limit=2' \
-H 'Authorization: Bearer sk_your_key'

List all AccountSettings (Connected Users)

This endpoint returns all AccountSettings (filtered by the applied below query parameters) associated with the connected users of a platform.


Parameters
account_idarray of stringsoptional

This parameter represents the account object with which the AccountSetting object is associated.

address.connected_userbooleanoptional

Indicates whether an address is available by default for a connected user.

address.connected_user_partnerbooleanoptional

Indicates whether an address is available by default for a connected user's partner.

address.partnerbooleanoptional

Indicates whether an address is available by default for a partner.

address.platformbooleanoptional

Indicates whether an address is available by default for a platform.

address.userbooleanoptional

Indicates whether an address is available by default for a user.

created.eqtimestampoptional

Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.

created.gttimestampoptional

Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.

created.gtetimestampoptional

Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.

created.lttimestampoptional

Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.

created.ltetimestampoptional

Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.

ending_beforestringoptional

A cursor for use in pagination. ending_before is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

limitintegeroptional

A limit on the number of objects to be returned, between 1 and 10. If this parameter is not specified, a default value of 10 is assumed.

payouts.enabledbooleanoptional

Whether Xflow can send payouts to this account. This parameter can be set by Xflow for a direct user or by the platform on behalf of a connected user. The former is an Xflow account of type=user which is not connected to an account of type=platform.

payouts.reason_code_not_enabledarray of stringsoptional

account_not_activated Payouts are not enabled on this account as it has not been activated.

platform_hold Payouts are not enabled on this account as they have been disabled by the platform.

xflow_hold Payouts are not enabled on this account as they have been disabled by Xflow.

starting_afterstringoptional

A cursor for use in pagination. starting_after is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, ending with obj_bar, your subsequent call can include starting_after=obj_bar in order to fetch the next page of the list.

GET /v1/account_settings/connected
curl -L -X GET 'https://api.xflowpay.com/v1/account_settings/connected?limit=2' \
-H 'Authorization: Bearer sk_your_key'

Addresses

Address objects represent a destination (for a store of value), which is usually an Xflow account.

The Address object

type: bank_accountcategory: xflow_receive
Parameters
bank_accounthash

Bank account details.

Child Parameters
billing_detailshash

Billing address.

Child Parameters
categoryenum

xflow_receive A destination (for a store of value) created by Xflow for the user to accept funds.

createdtimestamp

The seconds elapsed since Unix epoch time at which the address object was created.

currencystring

The ISO 4217 3-digit code for the amount currency.

idstring

Unique identifier for the object.

is_reusableboolean

Indicates whether the address is reusable for ACH debit.

linked_idstring

Unique identifier of an account object associated with this address. This is an account of type=partner or type=user or type=platform for address of category xflow_receive.

linked_objectenum

The type of object that this address object is associated with. This can only be account for now.

livemodeboolean

Has the value true if the object exists in livemode or the value false if the object exists in testmode.

metadatamap

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them.

namestring

Name on the destination (for a store of value).

objectstring

String representing the object’s type. Objects of the same type share the same value.

statusenum

activated Address is activated, and can be used to send or receive funds from.

deactivated Address is deactivated, and cannot be used to send or receive funds from.

expired Address is expired, and cannot be re-used to send or receive funds from.

pending_deactivation Address is scheduled to be deactivated.

supporting_documentationhash

Documents required to prove the authenticity of this destination (for a store of value).

Child Parameters
typeenum

Type of destination (for a store of value). This is bank_account for address of category xflow_receive.

wallethash

Not applicable.

The Address object
{
"bank_account": {
"domestic_credit": "000000007",
"domestic_debit": null,
"domestic_fast_credit": "000000007",
"domestic_wire": "000000008",
"global_wire": "XFLOWS33",
"iban": null,
"last4": "0400",
"number": "51744431540400"
},
"billing_details": null,
"category": "xflow_receive",
"created": 1709474909,
"currency": "USD",
"id": "address_f0A_1709474909321_p7bVk_000",
"is_reusable": false,
"linked_id": "account_F0A_1709429640704_QFIJN_000",
"linked_object": "account",
"livemode": false,
"metadata": null,
"name": null,
"object": "address",
"status": "activated",
"supporting_documentation": null,
"type": "bank_account",
"wallet": null
}

Create an Address

type: bank_accountcategory: user_payout (INR)
Parameters
bank_accounthashrequired

Bank account details.

Child Parameters
billing_detailshashrequired

Billing address.

Child Parameters
categoryenumrequired

This parameter indicates the category of the address. To create an address to pay out a user, this needs to be set to user_payout.

currencystringrequired

The ISO 4217 3-digit code for the amount currency. This should be set to INR.

linked_idstringrequired

Unique identifier of an account object associated with this address. This is an account of type=user or type=platform for address of category user_payout.

linked_objectenumrequired

The type of object that this address object is associated with. This can only be account for now.

metadatamapoptional

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them.

namestringrequired

Name on the destination (for a store of value).

supporting_documentationhashoptional

Documents required to prove the authenticity of this destination (for a store of value).

Child Parameters
typeenumrequired

Type of destination (for a store of value). This can only be a bank_account for now.

POST /v1/addresses
curl -L -X POST 'https://api.xflowpay.com/v1/addresses' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d $'{
"bank_account": {
"domestic_credit": "HDFC0000261",
"number": "5021102940182"
},
"billing_details": {
"city": "Bangalore",
"country": "IN",
"line1": "No. 7 MG Road",
"postal_code": "560038",
"state": "Karnataka"
},
"category": "user_payout",
"currency": "INR",
"linked_id": "account_F0A_1666077553446_41Hgq_000",
"linked_object": "account",
"name": "Marvelous Movies India. Pvt. Ltd.",
"type": "bank_account"
}'

Retrieve an Address

Parameters
No parameters required.
GET /v1/addresses/:id
curl -L -X GET 'https://api.xflowpay.com/v1/addresses/address_f0A_1666184962045_5J7h9_000' \
-H 'Authorization: Bearer sk_your_key'

Update an Address

Parameters
metadatamapoptional

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them.

POST /v1/addresses/:id
curl -L -X POST 'https://api.xflowpay.com/v1/addresses/address_f0A_1666184962045_5J7h9_000' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"metadata": {
"internal_reference": "ABC-1234"
}
}'

List all Addresses

Parameters
categoryarray of enumsoptional

Xflow categorization of destination (for a store of value).

partner_payment A destination (for a store of value) that the partner has paid the user from.

user_payout A destination (for a store of value) created by the user to pay themselves out.

xflow_checkout A destination (for a store of value) that was created for managing funds coming in through Checkout.

xflow_fee_advance A destination (for a store of value) created by Xflow for the platform user to maintain an advance balance to enable its connected users which have fees lower than the passthrough fees.

xflow_receive A destination (for a store of value) created by Xflow for the user to accept funds.

created.eqtimestampoptional

Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.

created.gttimestampoptional

Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.

created.gtetimestampoptional

Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.

created.lttimestampoptional

Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.

created.ltetimestampoptional

Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.

currencyarray of stringsoptional

The ISO 4217 3-digit code for the amount currency.

ending_beforestringoptional

A cursor for use in pagination. ending_before is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

is_reusablebooleanoptional

Indicates whether the addressable is reusable for ACH debit.

limitintegeroptional

A limit on the number of objects to be returned, between 1 and 10. If this parameter is not specified, a default value of 10 is assumed.

linked_idstringoptional

Unique identifier of an account object associated with this address. This is an account of:

type=partner or type=user or type=platform for addresses of category xflow_receive

type=user or type=platform for address of category user_payout

type=platform for addresses of category xflow_fee_advance

type=partner for addresses of category partner_payment, xflow_checkout

starting_afterstringoptional

A cursor for use in pagination. starting_after is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, ending with obj_bar, your subsequent call can include starting_after=obj_bar in order to fetch the next page of the list.

statusarray of enumsoptional

activated Address is activated, and can be used to send or receive funds from.

deactivated Address is deactivated, and cannot be used to send or receive funds from.

expired Address is expired, and cannot be re-used to send or receive funds from.

pending_deactivation Address is scheduled to be deactivated.

typearray of enumsoptional

Type of destination (for a store of value). This can be bank_account or wallet.

wallet.providerarray of enumsoptional

This can be affirm, afterpay, klarna or paypal_external.

GET /v1/addresses
curl -L -X GET 'https://api.xflowpay.com/v1/addresses?limit=2&status=activated' \
-H 'Authorization: Bearer sk_your_key'

Balance

The balance object represents a snapshot of the user's balance within Xflow.

The Balance object

Parameters
account_idstring

Unique identifier for the account object for which this balance is associated.

availablearray of hashes

Funds that are available to the user within Xflow. For example, this could be funds which have been reconciled, but have not yet been picked up by Xflow for payouts.

Child Parameters
fee_advancearray of hashes

Funds that have been transferred by the user to maintain balance within Xflow to enable connected users to have fees lower than the passthrough fees. This is [] for non-platform users.

Child Parameters
livemodeboolean

Has the value true if the object exists in livemode or the value false if the object exists in testmode.

objectstring

String representing the object’s type. Objects of the same type share the same value.

payout_processingarray of hashes

Funds that are being processed for payouts by Xflow.

Child Parameters
pendingarray of hashes

Funds that are not yet available to the user within Xflow. For example, this could be funds which have been received against a particular account identifier but have not yet been reconciled.

Child Parameters
processingarray of hashes

Funds that are being processed by Xflow. This is an intermediate state. For example, transfers may result in the funds being in the processing compartment momentarily, before they reach the destination compartment.

Child Parameters
The Balance object
{
"account_id": "account_F0A_1666077553446_41Hgq_000",
"available": [
{
"amount": "500.00",
"currency": "AED"
},
{
"amount": "9000.00",
"currency": "AUD"
},
{
"amount": "2000.00",
"currency": "CHF"
},
{
"amount": "410.00",
"currency": "CZK"
},
{
"amount": "5610.00",
"currency": "DKK"
},
{
"amount": "100.00",
"currency": "EUR"
},
{
"amount": "200.00",
"currency": "GBP"
},
{
"amount": "120.00",
"currency": "HKD"
},
{
"amount": "500.00",
"currency": "NOK"
},
{
"amount": "600.00",
"currency": "PLN"
},
{
"amount": "100.00",
"currency": "SEK"
},
{
"amount": "500.00",
"currency": "SGD"
},
{
"amount": "3400.00",
"currency": "USD"
}
],
"fee_advance": [],
"livemode": true,
"object": "balance",
"payout_processing": [
{
"amount": "0.00",
"currency": "AED"
},
{
"amount": "0.00",
"currency": "AUD"
},
{
"amount": "0.00",
"currency": "CHF"
},
{
"amount": "0.00",
"currency": "CZK"
},
{
"amount": "0.00",
"currency": "DKK"
},
{
"amount": "0.00",
"currency": "EUR"
},
{
"amount": "0.00",
"currency": "GBP"
},
{
"amount": "120.00",
"currency": "HKD"
},
{
"amount": "500.00",
"currency": "NOK"
},
{
"amount": "650.00",
"currency": "PLN"
},
{
"amount": "100.00",
"currency": "SEK"
},
{
"amount": "500.00",
"currency": "SGD"
},
{
"amount": "300.00",
"currency": "USD"
}
],
"pending": [
{
"amount": "100.00",
"currency": "AED"
},
{
"amount": "900.00",
"currency": "AUD"
},
{
"amount": "200.00",
"currency": "CHF"
},
{
"amount": "10.00",
"currency": "CZK"
},
{
"amount": "10.00",
"currency": "DKK"
},
{
"amount": "100.00",
"currency": "EUR"
},
{
"amount": "200.00",
"currency": "GBP"
},
{
"amount": "120.00",
"currency": "HKD"
},
{
"amount": "100.00",
"currency": "NOK"
},
{
"amount": "600.00",
"currency": "PLN"
},
{
"amount": "100.00",
"currency": "SEK"
},
{
"amount": "500.00",
"currency": "SGD"
},
{
"amount": "200.00",
"currency": "USD"
}
],
"processing": [
{
"amount": "500.00",
"currency": "AED"
},
{
"amount": "200.00",
"currency": "AUD"
},
{
"amount": "200.00",
"currency": "CHF"
},
{
"amount": "10.00",
"currency": "CZK"
},
{
"amount": "10.00",
"currency": "DKK"
},
{
"amount": "100.00",
"currency": "EUR"
},
{
"amount": "200.00",
"currency": "GBP"
},
{
"amount": "120.00",
"currency": "HKD"
},
{
"amount": "100.00",
"currency": "NOK"
},
{
"amount": "600.00",
"currency": "PLN"
},
{
"amount": "100.00",
"currency": "SEK"
},
{
"amount": "500.00",
"currency": "SGD"
},
{
"amount": "300.00",
"currency": "USD"
}
]
}

Retrieve Balance

Parameters
account_idstringoptional

Unique identifier for the account object for which this balance is associated. If this is not specified, then the balance object will be returned for the context that the user is in.

GET /v1/balance
curl -L -X GET 'https://api.xflowpay.com/v1/balance?account_id=account_F0A_1666077553446_41Hgq_000' \
-H 'Authorization: Bearer sk_your_key'

Retrieve Aggregate Partner Pending Balance

Parameters
account_idstringoptional

Unique identifier for the account object for which this balance is associated. If this is not specified, then the balance object will be returned for the context that the user is in.

GET /v1/balance/aggregate
curl -L -X GET 'https://api.xflowpay.com/v1/balance/aggregate?account_id=account_F0A_1666077553446_41Hgq_000' \
-H 'Authorization: Bearer sk_your_key'

BalanceTransactions

BalanceTransactions (BTs) are created by payments and represent funds being credited and debited in the Available and Pending compartments. Note that a single Payment can create multiple BTs.

The BalanceTransaction object

Parameters
amountstring

Amount value associated with the BalanceTransaction.

categorystring

available Funds that are available to the user within Xflow.

fee_advance Funds that have been sent by the user to manage shortfall in Xflow fees.

payout_processing Funds that are blocked for payouts within Xflow to the user.

pending Funds that are not yet available to the user within Xflow.

processing Funds that are blocked for processing by Xflow.

createdstring

The seconds elapsed since Unix epoch time at which the BalanceTransaction object was created.

currencystring

The ISO 4217 3-digit code for the amount currency.

idstring

Unique identifier for the object.

livemodeboolean

Has the value true if the object exists in live mode or the value false if the object exists in test mode.

objectstring

String representing the object’s type. Objects of the same type share the same value.

payment_idstring

Unique identifier for the payment object associated with the BalanceTransaction.

The BalanceTransaction object
{
"amount": "20.00",
"category": "available",
"created": 1666127190,
"currency": "USD",
"id": "bt_f0A_1666127190761_EZ7RC_000",
"livemode": true,
"object": "balance_transaction",
"payment_id": "payment_f0A_1666127190761_y0Yqq_000"
}

Retrieve a BalanceTransaction

Parameters
No parameters required.
GET /v1/balance_transactions/:id
curl -L -X GET 'https://api.xflowpay.com/v1/balance_transactions/bt_f0A_1666127190761_EZ7RC_000' \
-H 'Authorization: Bearer sk_your_key'

List all BalanceTransactions

Parameters
categoryarray of enumsoptional

available Funds that are available to the user within Xflow.

fee_advance Funds that have been sent by the user to manage shortfall in Xflow fees.

payout_processing Funds that are blocked for payouts within Xflow to the user.

pending Funds that are not yet available to the user within Xflow.

processing Funds that are blocked for processing by Xflow.

created.eqtimestampoptional

Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.

created.gttimestampoptional

Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.

created.gtetimestampoptional

Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.

created.lttimestampoptional

Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.

created.ltetimestampoptional

Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.

currencyarray of stringsoptional

The ISO 4217 3-digit code for the amount currency.

ending_beforestringoptional

A cursor for use in pagination. ending_before is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

limitintegeroptional

A limit on the number of objects to be returned, between 1 and 10. If this parameter is not specified, a default value of 10 is assumed.

payment_idarray of stringsoptional

Unique identifier for the payment object associated with the BalanceTransaction.

starting_afterstringoptional

A cursor for use in pagination. starting_after is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, ending with obj_bar, your subsequent call can include starting_after=obj_bar in order to fetch the next page of the list.

GET /v1/balance_transactions
curl -L -X GET 'https://api.xflowpay.com/v1/balance_transactions?currency=USD' \
-H 'Authorization: Bearer sk_your_key'

Deposits

Deposit objects are created by Xflow whenever funds are deposited into an Xflow account.

The Deposit object

Parameters
amountstring

Amount value that was deposited in Xflow. This value is negative in case of a dispute.

createdtimestamp

The seconds elapsed since Unix epoch time at which the deposit was created.

currencystring

The ISO 4217 3-digit code for the amount currency.

fromhash

Details of the account and address from which the funds are being deposited.

Child Parameters
idstring

Unique identifier for the object.

livemodeboolean

Has the value true if the object exists in livemode or the value false if the object exists in testmode.

metadatamap

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them.

objectstring

String representing the object’s type. Objects of the same type share the same value.

payment_methodenum

affirm Funds are transferred using Affirm, a Buy-Now-Pay-Later payment method.

afterpay Funds are transferred using Afterpay, a Buy-Now-Pay-Later payment method.

check Funds are transferred via a check.

domestic_credit Funds are transferred using local ACH credit.

domestic_debit Funds are debited using local ACH debit.

domestic_fast_credit Funds are transferred using fast local ACH credit.

domestic_wire Funds are transferred using domestic wire systems.

global_wire Funds are transferred using SWIFT.

klarna Funds are transferred using Klarna, a Buy-Now-Pay-Later payment method.

payment_method_detailshash

Details of the payment method being used for the deposit of funds.

Child Parameters
reason_codeenum

Reason why the deposit was declined or disputed. Possible values are cancelled, duplicate, general, high_risk, incorrect_amount, poor_image_quality, unmatched_details.

statement_descriptorstring

Narration available on the incoming deposit.

statusenum

initialized The deposit object has been created but has not yet been processed.

processing The deposit object is now being processed. Xflow does not know at this time whether it will complete successfully.

completed The deposit object has completed successfully. Funds are now available in Xflow.

cancelled The deposit object was cancelled before it was processed.

failed The deposit object failed processing.

reversed The deposit amount has been returned back to the source.

tohash

Details of the account and address to which the deposit is being made.

Child Parameters
The Deposit object
{
"amount": "20.00",
"created": 1666079759,
"currency": "USD",
"from": {
"account_id": "account_F0A_1666079163481_A7fje_000",
"address_id": "address_f0A_1666079747608_NDR0g_000"
},
"id": "deposit_f0A_1666079759165_P3FtR_000",
"livemode": true,
"metadata": null,
"object": "deposit",
"payment_method": "domestic_debit",
"payment_method_details": null,
"reason_code": null,
"statement_descriptor": "Online Payment for Invoice FY 2022-23-038",
"status": "completed",
"to": {
"account_id": "account_F0A_1666079163481_A7fje_000",
"address_id": "address_f0A_1666079171474_6jxOu_000"
}
}

Create a Deposit

This call works only in testmode.

Parameters
amountstringrequired

Amount value that was deposited in Xflow.

currencystringrequired

The ISO 4217 3-digit code for the amount currency. This can only be USD for now.

fromhashoptional

Details of the account and address from which the funds are being deposited.

Child Parameters
metadatamapoptional

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them.

payment_methodenumrequired

domestic_credit Funds are transferred using local ACH credit.

domestic_fast_credit Funds are transferred using fast local ACH credit.

domestic_wire Funds are transferred using domestic wire systems.

global_wire Funds are transferred using SWIFT.

statement_descriptorstringoptional

Narration available on the incoming deposit.

tohashrequired

Details of the account and address to which the deposit is being made.

Child Parameters
POST /v1/deposits
curl -L -X POST 'https://api.xflowpay.com/v1/deposits' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"amount": "20.00",
"currency": "USD",
"from": {
"account_id": "account_F0A_1666079163481_A7fje_000"
},
"payment_method": "domestic_credit",
"to": {
"account_id": "account_F0A_1666079163481_A7fje_000",
"address_id": "address_f0A_1666079171474_6jxOu_000"
}
}'

Retrieve a Deposit

Parameters
No parameters required.
GET /v1/deposits/:id
curl -L -X GET 'https://api.xflowpay.com/v1/deposits/deposit_f0A_1666079759165_P3FtR_000' \
-H 'Authorization: Bearer sk_your_key'

Update a Deposit

Parameters
metadatamapoptional

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them.

POST /v1/deposits/:id
curl -L -X POST 'https://api.xflowpay.com/v1/deposits/deposit_f0A_1666079759165_P3FtR_000' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"metadata": {
"internal_reference": "ABC-1234"
}
}'

List all Deposits

Parameters
created.eqtimestampoptional

Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.

created.gttimestampoptional

Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.

created.gtetimestampoptional

Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.

created.lttimestampoptional

Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.

created.ltetimestampoptional

Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.

currencyarray of stringsoptional

The ISO 4217 3-digit code for the amount currency.

ending_beforestringoptional

A cursor for use in pagination. ending_before is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

from.account_idstringoptional

Account identifier for the account from which funds are being deposited. Refer account object for more details.

from.address_idstringoptional

Address identifier of the account from which funds are being deposited. Refer address object for more details.

limitintegeroptional

A limit on the number of objects to be returned, between 1 and 10. If this parameter is not specified, a default value of 10 is assumed.

payment_methodarray of enumsoptional

affirm Funds are transferred using Affirm, a Buy-Now-Pay-Later payment method.

afterpay Funds are transferred using Afterpay, a Buy-Now-Pay-Later payment method.

check Funds are transferred via a check.

domestic_credit Funds are transferred using local ACH credit.

domestic_debit Funds are debited using local ACH debit.

domestic_fast_credit Funds are transferred using fast local ACH credit.

domestic_wire Funds are transferred using domestic wire systems.

global_wire Funds are transferred using SWIFT.

klarna Funds are transferred using Klarna, a Buy-Now-Pay-Later payment method.

reason_codearray of enumsoptional

Reason why the deposit was declined or disputed. Possible values are cancelled, duplicate, general, high_risk, incorrect_amount, poor_image_quality, unmatched_details.

starting_afterstringoptional

A cursor for use in pagination. starting_after is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, ending with obj_bar, your subsequent call can include starting_after=obj_bar in order to fetch the next page of the list.

statusarray of enumsoptional

initialized The deposit object has been created but has not yet been processed.

processing The deposit object is now being processed. Xflow does not know at this time whether it will complete successfully.

completed The deposit object has completed successfully. Funds are now available in Xflow.

cancelled The deposit object was cancelled before it was processed.

failed The deposit object failed processing.

reversed The deposit amount has been returned back to the source.

to.account_idstringoptional

Account identifier for the account to which funds are being deposited. Refer account object for more details.

to.address_idstringoptional

Address identifier of the account to which funds are being deposited. Refer address object for more details.

GET /v1/deposits
curl -L -X GET 'https://api.xflowpay.com/v1/deposits?payment_method=domestic_credit&status=initialized' \
-H 'Authorization: Bearer sk_your_key'

Events

Events are Xflow's way of letting you know when something interesting happens in your account. When an interesting event occurs, we create a new event object. For example, when a deposit is received, we create a deposit.status.completed event. Note that many API requests may cause multiple events to be created.

Events occur when the state of another API resource changes. For example, a deposit.status.completed event will contain a deposit and account.updated.payouts_enabled will contain an account. Individual Events don’t contain very much information on their own. This is by design, as the API structure can remain extremely stable and avoid difficult webhook migrations in the future as the Xflow API changes. If you need additional information, make a GET request to the API for that information. You can use the event.linked_id parameter to determine what resource to fetch from the API.

As with other API resources, you can use endpoints to retrieve an individual event or a list of events from the API. We also have a separate webhooks system for sending the event objects directly to an endpoint on your server. Webhooks are managed in your account settings, and our webhooks guide will help you get set up.

When using Xflow for Platforms, you can also receive notifications of events that occur in your platform and connected accounts.

NOTE: Right now, access to events through the Retrieve event API is guaranteed only for 30 days.

The Event object

Parameters
account_idstring

The identifier for the account to which the associated object that generated this event belongs.

createdtimestamp

The seconds elapsed since Unix epoch time at which the event was created.

idstring

Unique identifier for the object.

linked_idstring

The identifier of the object that generated this event.

linked_objectenum

The type of the object that generated this event.

livemodeboolean

Has the value true if the object exists in livemode or the value false if the object exists in testmode.

objectstring

String representing the object’s type. Objects of the same type share the same value.

typeenum

Description of the event (e.g., deposit.status.completed). You can find the full list of event types here.

The Event object
{
"account_id": "account_f0A_1648522874420_w8GTc_000",
"created": 1662917008,
"id": "event_f0A_1648522874420_w8GTc_000",
"linked_id": "deposit_f0A_1912224718366_laE3R_000",
"linked_object": "deposit",
"livemode": false,
"object": "event",
"type": "deposit.status.completed"
}

Retrieve an Event

Parameters
No parameters required.
GET /v1/events/:id
curl -L -X GET 'https://api.xflowpay.com/v1/events/event_f0A_1666079759165_P3FtR_000' \
-H 'Authorization: Bearer sk_your_key'

List all Events

Parameters
account_idstringoptional

The identifier for the account to which the associated object that generated this event belongs. This can be passed only by an account of type=platform.

created.eqtimestampoptional

Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.

created.gttimestampoptional

Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.

created.gtetimestampoptional

Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.

created.lttimestampoptional

Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.

created.ltetimestampoptional

Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.

ending_beforestringoptional

A cursor for use in pagination. ending_before is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

limitintegeroptional

A limit on the number of objects to be returned, between 1 and 10. If this parameter is not specified, a default value of 10 is assumed.

linked_idarray of stringsoptional

The identifier of the object that generated this event.

linked_objectarray of enumsoptional

The type of the object that generated this event.

starting_afterstringoptional

A cursor for use in pagination. starting_after is an object identifier that defines your place in the list. For instance, if you make a list request and receive 5 objects, ending with obj_bar, your subsequent call can include starting_after=obj_bar in order to fetch the next page of the list.

typearray of enumsoptional

Description of the event (e.g., deposit.status.completed). You can find the full list of event types here.

GET /v1/events
curl -L -X GET 'https://api.xflowpay.com/v1/events?limit=5' \
-H 'Authorization: Bearer sk_your_key'

Types of Events

This is a list of all the types of events we currently send. We may add more at any time, so in developing and maintaining your code, you should not assume that only these types exist.

You’ll notice that these events follow a pattern: resource.event.change. Our goal is to design a consistent system that makes things easier to anticipate and code against.

Parameters
account.address.activated

Occurs when the address parameter on the account transitions to activated.

account.payouts_enabled.updated

Occurs when there is a change in the value of the parameter account.payouts.enabled.

account.status.activated

Occurs when an account status has changed to activated.

account.status.hold

Occurs when an account status has changed to hold.