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.
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.
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.
{
"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.
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"
}
}'
{
"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.
An array containing the actual response elements, paginated by any request parameters.
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.
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.
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.
An array containing the actual response elements, paginated by any request parameters.
Whether or not there are more elements available after this set. If false, this set comprises the end of the list.
{
"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.
This parameter represents the state of the xflow_receive addresses associated with this account. The valid values include deactivated, requested, processing and activated.
Details about the business and activities that the account engages in.
The seconds elapsed since Unix epoch time at which the account was created.
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).
A file object identifier which contains a logo for the user to customize communications with their customers.
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.
Details of the supporting documentation for the account.
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.
{
"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"
}
Details about the business and activities that the account engages in.
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.
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
curl -L -X GET 'https://api.xflowpay.com/v1/accounts/account_F0A_1666184956871_JsBZ2_000' \
-H 'Authorization: Bearer sk_your_key'
Details about the business and activities that the account engages in.
A file object identifier which contains a logo for the user to customize communications with their customers.
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.
Details of the supporting documentation for the account.
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
This parameter represents the state of the xflow_receive addresses associated with this account. The valid values include deactivated, requested, processing and activated.
Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
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.
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.
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.
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.
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=usercreated by the platform - Address object of
type=user_payoutcreated 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:
- For
business_details.type=companyandlimited_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 insupporting_documentation.id_document. Remember to set the purpose for the file identifier totax_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 insupporting_documentation.id_document. Remember to set the purpose for the file identifier toadditional_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 insupporting_documentation.id_document. Remember to set the purpose for the file identifier toidentity_document
- For
business_details.type=sole_proprietorandindividual, 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 insupporting_documentation.id_document. Remember to set the purpose for the file identifier totax_document - The physical address details will have to be provided in
business_details.physical_addresshash
- 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 insupporting_documentation.id_document. Remember to set the purpose for the file identifier toidentity_document
- 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_partnershipandpartnership: 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 availablesole_proprietorandindividual:person.relationship.ownermust 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.
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.
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.
This parameter represents the account object with which the AccountSetting object is associated.
Default values for address of category xflow_receive availability for different types of accounts.
Default values for the currency for address of category xflow_receive for different types of accounts.
The seconds elapsed since Unix epoch time at which the AccountSetting was created.
Indicates whether live FX is enabled for a platform's connected users. If true, payouts are processed immediately for all connected users.
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
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.
{
"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
curl -L -X GET 'https://api.xflowpay.com/v1/account_settings/account_setting_F0A_1666184956871_JsBZ2_000' \
-H 'Authorization: Bearer sk_your_key'
Default values for address of category xflow_receive availability for different types of accounts.
Default values for address of category xflow_receive availability for different types of accounts.
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.
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
This parameter represents the account object with which the AccountSetting object is associated.
Indicates whether an address is available by default for a connected user.
Indicates whether an address is available by default for a connected user's partner.
Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
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.
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.
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.
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.
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.
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.
This parameter represents the account object with which the AccountSetting object is associated.
Indicates whether an address is available by default for a connected user.
Indicates whether an address is available by default for a connected user's partner.
Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
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.
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.
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.
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.
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.
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.
xflow_receive A destination (for a store of value) created by Xflow for the user to accept funds.
The seconds elapsed since Unix epoch time at which the address object was created.
The ISO 4217 3-digit code for the amount currency.
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.
The type of object that this address object is associated with. This can only be account for now.
Has the value true if the object exists in livemode or the value false if the object exists in testmode.
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.
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.
Documents required to prove the authenticity of this destination (for a store of value).
Type of destination (for a store of value). This is bank_account for address of category xflow_receive.
{
"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
}
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.
The ISO 4217 3-digit code for the amount currency. This should be set to INR.
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.
The type of object that this address object is associated with. This can only be account for now.
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.
Documents required to prove the authenticity of this destination (for a store of value).
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
curl -L -X GET 'https://api.xflowpay.com/v1/addresses/address_f0A_1666184962045_5J7h9_000' \
-H 'Authorization: Bearer sk_your_key'
Update an Address
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.
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
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.
Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
The ISO 4217 3-digit code for the amount currency.
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.
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.
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
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.
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.
Type of destination (for a store of value). This can be bank_account or wallet.
curl -L -X GET 'https://api.xflowpay.com/v1/addresses?limit=2&status=activated' \
-H 'Authorization: Bearer sk_your_key'
The Balance object
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.
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.
Has the value true if the object exists in livemode or the value false if the object exists in testmode.
Funds that are being processed for payouts by Xflow.
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.
{
"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
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
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
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.
The seconds elapsed since Unix epoch time at which the BalanceTransaction object was created.
The ISO 4217 3-digit code for the amount currency.
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
{
"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
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
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.
Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
The ISO 4217 3-digit code for the amount currency.
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.
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.
Unique identifier for the payment object associated with the BalanceTransaction.
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.
curl -L -X GET 'https://api.xflowpay.com/v1/balance_transactions?currency=USD' \
-H 'Authorization: Bearer sk_your_key'
The Deposit object
The seconds elapsed since Unix epoch time at which the deposit was created.
The ISO 4217 3-digit code for the amount currency.
Details of the account and address from which the funds are being deposited.
Has the value true if the object exists in livemode or the value false if the object exists in testmode.
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.
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.
Details of the payment method being used for the deposit of funds.
Reason why the deposit was declined or disputed. Possible values are cancelled, duplicate, general, high_risk, incorrect_amount, poor_image_quality, unmatched_details.
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.
{
"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.
The ISO 4217 3-digit code for the amount currency. This can only be USD for now.
Details of the account and address from which the funds are being deposited.
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.
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.
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
curl -L -X GET 'https://api.xflowpay.com/v1/deposits/deposit_f0A_1666079759165_P3FtR_000' \
-H 'Authorization: Bearer sk_your_key'
Update a Deposit
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.
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
Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
The ISO 4217 3-digit code for the amount currency.
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.
Account identifier for the account from which funds are being deposited. Refer account object for more details.
Address identifier of the account from which funds are being deposited. Refer address object for more details.
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.
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 why the deposit was declined or disputed. Possible values are cancelled, duplicate, general, high_risk, incorrect_amount, poor_image_quality, unmatched_details.
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.
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.
Account identifier for the account to which funds are being deposited. Refer account object for more details.
Address identifier of the account to which funds are being deposited. Refer address object for more details.
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
The identifier for the account to which the associated object that generated this event belongs.
The seconds elapsed since Unix epoch time at which the event was created.
Has the value true if the object exists in livemode or the value false if the object exists in testmode.
Description of the event (e.g., deposit.status.completed). You can find the full list of event types here.
{
"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
curl -L -X GET 'https://api.xflowpay.com/v1/events/event_f0A_1666079759165_P3FtR_000' \
-H 'Authorization: Bearer sk_your_key'
List all Events
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.
Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
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.
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.
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.
Description of the event (e.g., deposit.status.completed). You can find the full list of event types here.
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.
Occurs when there is a change in the value of the parameter account.payouts.enabled.
Occurs when a payout enters processing state. At this time, the payout amount cannot be changed.
Occurs whenever funds for a payout have been debited and left the Xflow platform.
Occurs when a payout status changes to hold. Please contact support@xflowpay.com to find out what the issue is.
Occurs when funds for a previously settled payout have been returned by the beneficiary bank.
Occurs whenever a Payment Advice is available for a payout that took place in the past.
Occurs when funds from the receivable have been debited for payout.
Occurs when a receivable has been activated. The receivable is now ready to receive funds.
Occurs when the funds received by the receivable are equivalent to the funds set on the amount_maximum_reconcilable parameter.
Occurs when the receivable status changes to hold. Please contact support@xflowpay.com to find out what the issue is.
Occurs when the receivable status changes to input_required. This means that you need to provide some information and submit the receivable again to Xflow for verification.
ExchangeRates
The ExchangeRate object models the details behind currency conversion. It transparently offers details like the buy and sell amounts, what the mid-market (or inter-bank) and the user-facing rates are and (if applicable) how long the rates are valid. The ExchangeRate object is always created by a payment object.
The seconds elapsed since Unix epoch time at which the ExchangeRate was created.
Dealt currency denotes the fixed side of the conversion request. If buy.amount was specified, then buy.currency; else, sell.currency (in 3-letter ISO 4217 format).
Has the value true if the object exists in livemode or the value false if the object exists in testmode.
{
"buy": {
"amount": "37628.10",
"currency": "INR"
},
"created": 1716229825,
"currency_pair": "USDINR",
"dealt_currency": "USD",
"id": "fx_f0A_1716229825555_EWmW0_000",
"livemode": true,
"object": "exchange_rate",
"payment_id": "payment_f0A_1716217802597_jZR51_000",
"rate": {
"inter_bank": null,
"mid_market": "83.31252",
"user": "83.31252",
"valid_from": 1716220800,
"valid_to": 1716231600
},
"sell": {
"amount": "451.65",
"currency": "USD"
},
"type": "lock"
}
Retrieve an ExchangeRate
curl -L -X GET 'https://api.xflowpay.com/v1/exchange_rates/fx_f0A_1666161932110_XIyNE_000' \
-H 'Authorization: Bearer sk_your_key'
List all ExchangeRates
The ISO 4217 3-digit code for the buy amount currency.
Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
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.
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.
Unique identifier for the payment object associated with the ExchangeRate.
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.
The ISO 4217 3-digit code for the sell amount currency.
curl -L -X GET 'https://api.xflowpay.com/v1/exchange_rates?limit=5' \
-H 'Authorization: Bearer sk_your_key'
FeePlans
The FeePlan object models the different fees for a platform, direct user and connected user.
The seconds elapsed since Unix epoch time at which the FeePlan was created.
The type of object that this FeePlan object is associated with. This can only be account for now.
Has the value true if the object exists in livemode, the value false if the object exists in testmode.
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.
account_fees Xflow fees which are set by Xflow for a platform. These fees indicate what Xflow will charge the account for money movement.
account_fees_passthrough Xflow fees which are set on account of type=platform and passed onto the connected user by default (the platform has the option to mark up these fees for their connected users) during connected user creation.
{
"created": 1666077553,
"deposit": [],
"id": "fee_plan_F0A_1666077553446_a8fQ1_000",
"linked_id": "account_F0A_1666077553446_41Hgq_000",
"linked_object": "account",
"livemode": true,
"metadata": null,
"object": "fee_plan",
"payout": [
{
"destination_currency": "*",
"fixed": "0.00",
"minimum": "0.00",
"source_currency": "*",
"variable": "1.00"
},
{
"destination_currency": "*",
"fixed": "100.00",
"minimum": "0.00",
"source_currency": "AUD",
"variable": "1.00"
},
{
"destination_currency": "*",
"fixed": "100.00",
"minimum": "0.00",
"source_currency": "EUR",
"variable": "1.00"
},
{
"destination_currency": "*",
"fixed": "100.00",
"minimum": "0.00",
"source_currency": "GBP",
"variable": "1.00"
}
],
"payout_fx": [
{
"destination_currency": "*",
"reference_rate": "mid_market",
"source_currency": "*",
"variable": "1.00"
},
{
"destination_currency": "INR",
"reference_rate": "mid_market",
"source_currency": "EUR",
"variable": "0.75"
}
],
"status": "activated",
"transfer_fx": [
{
"destination_currency": "*",
"reference_rate": "mid_market",
"source_currency": "*",
"variable": "1.00",
"variable_off_hours": "2.00"
},
{
"destination_currency": "GBP",
"reference_rate": "mid_market",
"source_currency": "EUR",
"variable": "0.75",
"variable_off_hours": "2.00"
}
],
"type": "account_fees",
"validity": {
"from": 1683072939,
"to": null
}
}
The type of object that this FeePlan object is associated with. This can only be account for now.
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.
Payout fee details. At least one value for this array is required and there should exist a value that has both destination_currency and source_currency as *.
Payout FX fee details. At least one value for this array is required and there should exist a value that has both destination_currency and source_currency as *.
Transfer FX fee details. At least one value for this array is required and there should exist a value that has both destination_currency and source_currency as *.
curl -L -X POST 'https://api.xflowpay.com/v1/fee_plans' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Xflow-Account: "account_F0A_1666067120934_238hc_000"' \
-H 'Content-Type: application/json' \
-d '{
"linked_id": "account_F0A_1666077553446_41Hgq_000",
"linked_object": "account",
"payout": [
{
"destination_currency": "*",
"fixed": "0.00",
"minimum": "0.00",
"source_currency": "*",
"variable": "1.00"
},
{
"destination_currency": "*",
"fixed": "100.00",
"minimum": "0.00",
"source_currency": "EUR",
"variable": "1.00"
},
{
"destination_currency": "*",
"fixed": "100.00",
"minimum": "0.00",
"source_currency": "GBP",
"variable": "1.00"
}
],
"payout_fx": [
{
"destination_currency": "*",
"reference_rate": "mid_market",
"source_currency": "*",
"variable": "1.00"
},
{
"destination_currency": "INR",
"reference_rate": "mid_market",
"source_currency": "EUR",
"variable": "0.75"
}
],
"transfer_fx": [
{
"destination_currency": "*",
"reference_rate": "mid_market",
"source_currency": "*",
"variable": "1.00",
"variable_off_hours": "2.00"
},
{
"destination_currency": "GBP",
"reference_rate": "mid_market",
"source_currency": "EUR",
"variable": "0.75",
"variable_off_hours": "2.00"
}
],
"type": "account_fees"
}'
Retrieve a FeePlan
curl -L -X GET 'https://api.xflowpay.com/v1/fee_plans/fee_plan_f0A_1666184962045_5J7h9_000' \
-H 'Authorization: Bearer sk_your_key'
Update a FeePlan
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.
curl -L -X POST 'https://api.xflowpay.com/v1/fee_plans/fee_plan_F0A_1689434448849_Yi6W3_000' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"metadata": {
"internal_name": "Shoe and Sock Power"
}
}'
List all FeePlans
Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
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.
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.
Unique identifier of an account object associated with this FeePlan.
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.
account_fees Xflow fees which are set by Xflow for a platform. These fees indicate what Xflow will charge the account for money movement.
account_fees_passthrough Xflow fees which are set on account of type=platform and passed onto the connected user by default (the platform has the option to mark up these fees for their connected users) during connected user creation.
Return results where the validity.from field is equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the validity.from field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the validity.from field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the validity.from field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the validity.from field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the validity.to field is equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the validity.to field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the validity.to field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the validity.to field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the validity.to field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
curl -L -X GET 'https://api.xflowpay.com/v1/fee_plans?limit=2' \
-H 'Authorization: Bearer sk_your_key'
Files
Files are documents provided by an account for a specific purpose. You can create new files accounts and retrieve existing files.
The File object
The seconds elapsed since Unix epoch time at which the file was created.
Has the value true if the object exists in livemode or the value false if the object exists in testmode.
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.
Purpose for uploading the file.
additional_verification Documents required for Xflow to conduct additional verification. This is rare! Xflow Support will reach out to you directly in case these are required (e.g. Bank Statement).
finance_document Documents like an invoice.
identity_document Documents to verify the business or individual identity (e.g. Tax identifier of a business owner, cancelled cheque which has the merchant's name).
logo Documents like a logo.
payout_confirmation Documents like MT103, Payment Advice, etc.
tax_document Documents like Form 15CA and Form 15CB (India-specific) that show tax has been properly accounted for specific transactions.
The formats supported for all documents are jpeg, pdf and png. The maximum size allowed is 10MB. All documents are downloadable and never expire.
{
"created": 1675153265,
"file_name": "business_pan.pdf",
"id": "file_F0A_1675153265850_IREzx_000",
"livemode": false,
"metadata": null,
"object": "file",
"purpose": "identity_document",
"size": 493117,
"type": "pdf",
"url": "https://api.xflowpay.com/v1/files/file_F0A_1675153265850_IREzx_000/contents"
}
Create a File
A file to upload. The file should follow the specifications of RFC 2388 (which defines file transfers for the multipart/form-data protocol).
Purpose for uploading the file.
additional_verification Documents required for Xflow to conduct additional verification. This is rare! (e.g. Bank Statement).
finance_document Documents like an invoice.
identity_document Documents to verify the account or individual identity (e.g. Tax identifier of a business owner, cancelled cheque which has the merchant's name).
logo Documents like a logo.
payout_confirmation Documents like MT103, Payment Advice, etc.
tax_document Tax documents (e.g. Form 15CA and Form 15CB in India).
The formats supported for all documents are jpeg, pdf and png. The maximum size allowed is 10MB. All documents are downloadable and never expire.
curl -L -X POST 'https://api.xflowpay.com/v1/files' \
-H 'Authorization: Bearer sk_your_key' \
-F file=@"business_pan.pdf" \
-F payload='{
"purpose": "identity_document"
}'
Retrieve a File
curl -L -X GET 'https://api.xflowpay.com/v1/files/file_f0A_1646922573131_7jZ7z_000' \
-H 'Authorization: Bearer sk_your_key'
Update a File
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.
curl -L -X POST 'https://api.xflowpay.com/v1/files/file_f0A_1646922573131_7jZ7z_000' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"metadata": {
"internal_reference": "ABC-1234"
}
}'
List all Files
Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
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.
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.
Filtering on the following statuses is supported (you can also query for multiple statuses in the same query): additional_verification, finance_document, identity_document, logo, payout_confirmation and tax_document.
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.
curl -L -X GET 'https://api.xflowpay.com/v1/files?purpose=finance_document&type=pdf' \
-H 'Authorization: Bearer sk_your_key'
Download a File
curl -L -X GET 'https://api.xflowpay.com/v1/files/file_f0A_1646922573131_7jZ7z_000/contents' \
-H 'Authorization: Bearer sk_your_key'
PaymentLinks
A PaymentLink object enables a Xflow user to send a payment link to a partner to collect money.
The PaymentLink object
The seconds elapsed since Unix epoch time at which the PaymentLink object was created.
The seconds elapsed since Unix epoch time at which the PaymentLink object will expire.
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
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.
Array of unique identifiers of the receivable objects associated with the PaymentLink. Currently you can have only one receivable associated with a PaymentLink object.
activated PaymentLink object is activated.
deactivated PaymentLink object is deactivated.
expired PaymentLink object has expired.
{
"account_id": "account_F0A_1666079163481_A7fje_000",
"created": 1666079629,
"expires_at": 1671263628,
"id": "pl_F0A_1666079628988_OkOfM_000",
"link": "https://checkout.xflowpay.com/checkout/pl_F0A_1666079628988_OkOfM_000",
"livemode": true,
"metadata": null,
"object": "payment_link",
"receivable_ids": [
"receivable_f0A_1666079293438_eDQAH_000"
],
"status": "expired",
"type": "receivable"
}
Create a PaymentLink
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.
Array of unique identifiers of the receivable objects associated with the PaymentLink. Currently you can have only one receivable associated with a PaymentLink object.
curl -L -X POST 'https://api.xflowpay.com/v1/payment_links' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"account_id": "account_F0A_1666079163481_A7fje_000",
"receivable_ids": [
"receivable_f0A_1666079293438_eDQAH_000"
],
"type": "receivable"
}'
Retrieve a PaymentLink
curl -L -X GET 'https://api.xflowpay.com/v1/payment_links/pl_F0A_1666079628988_OkOfM_000' \
-H 'Authorization: Bearer sk_your_key'
Update a PaymentLink
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.
curl -L -X POST 'https://api.xflowpay.com/v1/payment_links/pl_F0A_1666079628988_OkOfM_000' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"metadata": {
"internal_reference": "ABC-1234"
}
}'
List all PaymentLink
Unique identifier for the account object associated with the PaymentLink.
Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
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.
Return results where the expires_at field is equal to the timestamp value in seconds elapsed since Unix epoch time. Objects returned as part of this list query are sorted in ascending order based on the expires_at parameter.
Return results where the expires_at field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the expires_at field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the expires_at field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the expires_at field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Unique identifier for a receivable object which when passed, returns a list of associated PaymentLink objects.
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.
activated PaymentLink is activated.
deactivated PaymentLink is deactivated.
expired PaymentLink has expired.
curl -L -X GET 'https://api.xflowpay.com/v1/payment_links?expires_at.lt=1671263628&status=activated' \
-H 'Authorization: Bearer sk_your_key'
Activate a PaymentLink
curl -L -X POST 'https://api.xflowpay.com/v1/payment_links/pl_F0A_1666079628988_OkOfM_000/activate' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json'
Deactivate a PaymentLink
curl -L -X POST 'https://api.xflowpay.com/v1/payment_links/pl_F0A_1666079628988_OkOfM_000/deactivate' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json'
Expire a PaymentLink
Expire is applicable only if there is a receivable object linked to the PaymentLink.
curl -L -X POST 'https://api.xflowpay.com/v1/payment_links/pl_F0A_1666079628988_OkOfM_000/expire' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json'
Extend a PaymentLink
Moves forward the expiry date of the PaymentLink object by one week. Extend is applicable only if there is a receivable object linked to the PaymentLink.
curl -L -X POST 'https://api.xflowpay.com/v1/payment_links/pl_F0A_1666079628988_OkOfM_000/extend' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json'
Payments
Payment objects model real-world money movement into, within and out of Xflow. Payments lead to movement of money from source to destination and result in the creation of BalanceTransactions. Payments between different types of currencies will result in the creation of an ExchangeRate object. Xflow models fees as distinct payments as well.
The Payment object
The seconds elapsed since Unix epoch time at which the payment object was created.
Unique identifier for the FeePlan object associated with this payment. This parameter is non-null for fees related payments.
Details of the account & currency from which the funds are being transferred.
Has the value true if an ExchangeRate object is associated with this payment, otherwise the value is false.
String representing the linked object’s type. Objects of the same type share the same value.
This array of hashes contains details of the linked payment IDs.
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
The seconds elapsed since Unix epoch time at which the payment becomes eligible for payout. This is applicable only for payment type reconcile.
adjustment_negative Money adjustment where Xflow removes funds from the user's balance (this is rare).
adjustment_positive Money adjustment where Xflow adds funds to the user's balance (this is rare).
deposit_reversal Money returned back to the source from Xflow.
fee_advance_debit Money moving from the platform fee_advance balance to compensate Xflow for fees shortfall.
funds_credit Money moving into Xflow from user or partner.
funds_debit Money moving from a receivable object to a payout object.
fx_fee Represents Xflow fees deducted for FX markup.
payout Money moving from Xflow to a user-specified destination (for a store of value).
payout_failure Money moving back into Xflow after a failed payout attempt.
payout_fee Represents Xflow fees deducted for a payout that Xflow makes to the user.
platform_partner_debit Represents money earmarked for movement from the platform partner pending balance for Xflow fees.
processing_fee Represents Xflow fees deducted for processing a payment made by a partner through PaymentLinks. This fee can be deducted from the user or partner based on processing_fee_indicator hash on the account of type=user.
reconcile Money moving to a receivable object as a result of an explicit reconcile action.
reconcile_paypal Money moving directly via PayPal to the user without entering Xflow.
transfer Money moving within user across currencies or money moving between partners in the same currency.
{
"created": 1666160776,
"fee_plan_id": "fee_plan_F0A_1666077553446_a8sn4_000",
"from": {
"amount": "19.65",
"currency": "USD"
},
"id": "payment_f0A_1666160776922_DkBou_000",
"is_exchange_rate_applicable": true,
"linked_id": "payout_f0A_1666160776922_Q1hjW_000",
"linked_object": "payout",
"linked_payments": [
{
"account_id": "account_f0A_2396160776922_Q1hjW_000",
"payment_id": "payment_f0A_1666160779999_ABCou_000",
"payment_type": "funds_debit"
}
],
"livemode": true,
"object": "payment",
"payout_eligible_at": null,
"to": {
"amount": "1600.57",
"currency": "INR"
},
"type": "payout"
}
Retrieve a Payment
curl -L -X GET 'https://api.xflowpay.com/v1/payments/payment_f0A_1666160776922_DkBou_000' \
-H 'Authorization: Bearer sk_your_key'
List all Payments
Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
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.
The ISO 4217 3-digit code for the from amount currency.
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.
Unique identifier for the object that created this underlying payment object.
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.
The ISO 4217 3-digit code for the to amount currency.
adjustment_negative Money adjustment where Xflow removes funds from the user's balance (this is rare).
adjustment_positive Money adjustment where Xflow adds funds to the user's balance (this is rare).
deposit_reversal Money returned back to the source from Xflow.
fee_advance_debit Money moving from the platform fee_advance balance to compensate Xflow for fees shortfall.
funds_credit Money moving into Xflow from user or partner.
funds_debit Money moving from a receivable object to a payout object.
fx_fee Represents Xflow fees deducted for FX markup.
payout Money moving from Xflow to a user-specified destination (for a store of value).
payout_failure Money moving back into Xflow after a failed payout attempt.
payout_fee Represents Xflow fees deducted for a payout that Xflow makes to the user.
platform_currency_credit Represents money credited to a platform currency balance.
platform_currency_debit Represents money debited from a platform currency balance. This will always have an ExchangeRate object associated with it.
platform_partner_debit Represents money earmarked for movement from the platform partner pending balance for Xflow fees.
processing_fee Represents Xflow fees deducted for processing a payment made by a partner through PaymentLinks. This fee can be deducted from the user or partner based on processing_fee_indicator hash on the account of type=user.
reconcile Money moving to a receivable object as a result of an explicit reconcile action.
reconcile_paypal Money moving directly via PayPal to the user without entering Xflow.
transfer Money moving within user across currencies or money moving between partners in the same currency.
curl -L -X GET 'https://api.xflowpay.com/v1/payments?type=fees' \
-H 'Authorization: Bearer sk_your_key'
Payouts
Payout objects are created by Xflow whenever funds are moved out of an Xflow account into a real-world destination (for a store of value).
The Payout object
The seconds elapsed since Unix epoch time at which the funds are expected to be credited at the specified address. Put another way, this is the date the the payout is expected to arrive in the bank. This factors in delays like weekends or bank holidays.
Has the value true if automatic payouts are enabled and has the value false if manual payouts are enabled. Currently, Xflow supports automatic payouts only.
The seconds elapsed since Unix epoch time at which the payout object was created.
The ISO 4217 3-digit code for the amount currency.
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
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.
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.
Details of the payment method being used for the payout of funds.
File object providing details of the payout amount. E.g. - MT 103, Payment Advice.
initialized The payout object has been created but has not yet been processed.
processing The payout object is now being processed.
settled The payout object has completed successfully. Xflow does not know when exactly the payout will be deposited in your account.
failed The payout object has failed. Please reach out to Xflow Operations team.
hold The payout object is on hold. Please reach out to Xflow Operations team.
cancelled The payout object has cancelled by Xflow.
{
"amount": "1600.57",
"arrival_date": null,
"automatic": true,
"created": 1666160776,
"currency": "INR",
"id": "payout_f0A_1666160776922_Q1hjW_000",
"livemode": true,
"metadata": null,
"object": "payout",
"payment_method": "domestic_credit",
"payment_method_details": null,
"payout_confirmation": null,
"statement_descriptor": "XFLOW PAYOUT F0A-1666160776922-J2uic-000",
"status": "processing",
"to": {
"account_id": "account_F0A_1666077553446_41Hgq_000",
"address_id": "address_f0A_1666160723235_fJSRH_000"
}
}
Retrieve a Payout
curl -L -X GET 'https://api.xflowpay.com/v1/payouts/payout_f0A_1666160776922_Q1hjW_000' \
-H 'Authorization: Bearer sk_your_key'
Update a Payout
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.
curl -L -X POST 'https://api.xflowpay.com/v1/payouts/payout_f0A_1666160776922_Q1hjW_000' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"metadata": {
"internal_reference": "ABC-1234"
}
}'
List all Payouts
Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
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.
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.
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.
initialized The payout object has been created but has not yet been processed.
processing The payout object is now being processed.
settled The payout object has completed successfully. Xflow does not know when exactly the payout will be deposited in your account.
failed The payout object has failed. Please reach out to Xflow Operations team.
hold The payout object is on hold. Please reach out to Xflow Operations team.
cancelled The payout object has cancelled by Xflow.
Account identifier for the account to which funds are being deposited. Refer account object for more details.
Address identifier of the account to which funds are being deposited. Refer address object for more details.
curl -L -X GET 'https://api.xflowpay.com/v1/payouts?status=processing' \
-H 'Authorization: Bearer sk_your_key'
The Person object
The seconds elapsed since Unix epoch time at which the person object was created.
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
pending shows a person that has been submitted for activation along with an account.
unverified shows a person that has not been submitted for activation along with an account.
verified shows a person that has an account that has been activated.
Documents required to prove relationship of the person with the account.
{
"created": 1666078214,
"full_name": "Jerome Kratif",
"id": "person_F0A_1666078214977_3Du5D_000",
"livemode": true,
"object": "person",
"relationship": {
"director": true,
"owner": false,
"representative": false
},
"status": "unverified",
"supporting_documentation": {
"id_document": "file_F0A_1666078189630_vD3vd_000"
},
"supporting_ids": {
"tax": "AFBPB8012E"
}
}
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_partnershipandpartnership: 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 availablesole_proprietorandindividual:person.relationship.ownermust be set to true and no other relationships are possible
Documents required to prove relationship of the person with the account.
curl -L -X POST 'https://api.xflowpay.com/v1/persons' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"relationship": {
"director": true
},
"supporting_documentation": {
"id_document": "file_F0A_1666078189630_vD3vd_000"
}
}'
Retrieve a Person
curl -L -X GET 'https://api.xflowpay.com/v1/persons/person_F0A_1666078214977_3Du5D_000' \
-H 'Authorization: Bearer sk_your_key'
Update a Person
Documents required to prove relationship of the person with the account.
curl -L -X POST 'https://api.xflowpay.com/v1/persons/person_F0A_1666078214977_3Du5D_000' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"relationship": {
"owner": true
},
"supporting_documentation": {
"id_document": "file_F0A_2934778189630_vD3vd_000"
}
}'
Delete a Person
curl -L -X DELETE 'https://api.xflowpay.com/v1/persons/person_F0A_1666078214977_3Du5D_000' \
-H 'Authorization: Bearer sk_your_key'
List all Persons
Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
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.
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.
true if the person is the director of the account entity, false otherwise.
true if the person is the owner of the account entity, false otherwise.
true if the person is the representative of the account entity, false otherwise.
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.
curl -L -X GET 'https://api.xflowpay.com/v1/persons?limit=2' \
-H 'Authorization: Bearer sk_your_key'
The Quote object
Dealt currency denotes the fixed side of the conversion request. If buy.amount was specified, then buy.currency; else, sell.currency (in 3-letter ISO 4217 format).
Has the value true if the object exists in livemode or the value false if the object exists in testmode.
{
"buy": {
"amount": "8253.63",
"currency": "INR"
},
"currency_pair": "USDINR",
"dealt_currency": "USD",
"fee_plan_id": "fee_plan_F0A_1710758832717_DN6T5_000",
"livemode": false,
"object": "quote",
"rate": {
"inter_bank": null,
"mid_market": "83.37002",
"user": "82.53632",
"valid_from": 1716220800,
"valid_to": 1716231600
},
"sell": {
"amount": "100.00",
"currency": "USD"
},
"type": "payout_fx"
}
Retrieve a Quote
To retrieve a quote, provide either sell.amount, sell.currency and buy.currency or buy.amount, buy.currency and sell.currency.
curl -L -X GET 'https://api.xflowpay.com/v1/quotes?buy.amount=-100.45&buy.currency=INR&sell.amount=&sell.currency=USD&type=payout_fx' \
-H 'Authorization: Bearer sk_your_key'
Receivables
The receivable object represents an intent expressed by the user to accept funds from their partners. Typically, this intent is expressed by providing an underlying invoice for the desired inflow of funds.
The Receivable object
Amount value that is unavailable for reconciliation because Xflow is processing a payment of an equivalent amount. The value includes locks linked to payments being processed by Xflow and Xflow’s partner providers like PayPal. Locked value associated with Xflow-processed payments can be identified through the field deposit_ids_amount_locked.
Maximum amount value that can be reconciled. This field can be edited by the user.
Amount value that is available for reconciliation. This field is a calculated field and is returned by Xflow. The formula to calculate this value is amount_reconcilable = amount_maximum_reconcilable - (amount_locked + amount_reconciled)
Amount value that has been reconciled. This is a calculated field and is returned by Xflow. The value is inclusive of reconciliations linked to payments that have been or will be settled by Xflow, and Xflow’s partner providers like PayPal. Reconciled value for payments settled by Xflow can be calculated as amount_reconciled_not_settled + amount_settled_payouts + fees. Reconciled value linked to payments settled by other providers can be calculated as amount_reconciled - amount_reconciled_not_settled - amount_settled_payouts - fees.
Amount value that has been reconciled but not paid out. This is a calculated field and is returned by Xflow.
Amount value that has been transferred for payout. This is a calculated field and is returned by Xflow.
The seconds elapsed since Unix epoch time at which the receivable object was created.
The ISO 4217 3-digit code for the amount currency.
Represents an array of deposit objects due to which amount is locked.
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
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.
Purpose codes defined by the Financial Regulator for cross-border transactions.
draft The receivable is in draft state, and has not been submitted for verification.
verifying The receivable is being verified by the Xflow Operations team.
activated The receivable is activated, amount can be reconciled.
completed The receivable is completed, meaning amount_settled_payouts = amount_maximum_reconcilable.
cancelled The receivable is cancelled, amount can no longer be reconciled.
hold The receivable is being held due to (i) receivable verification process outcome (ii) associated partner or user in hold status or (iii) associated partner in deactivated status.
input_required The receivable requires input from the user.
{
"account_id": "account_F0A_1666079163481_A7fje_000",
"amount_locked": "0.00",
"amount_maximum_reconcilable": "50.00",
"amount_reconcilable": "30.00",
"amount_reconciled": "20.00",
"amount_reconciled_not_settled": "0.00",
"amount_settled_payouts": "19.95",
"created": 1666079293,
"currency": "USD",
"deposit_ids_amount_locked": [],
"description": "This invoice is for insights into the payments world",
"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": null,
"object": "receivable",
"purpose_code": "P1006",
"purpose_code_description": "Business and management consultancy and public relations services",
"status": "activated",
"system_message": [],
"transaction_type": "services"
}
Create a Receivable
Maximum amount value that can be reconciled on this receivable.
The ISO 4217 3-digit code for the amount currency.
An arbitrary string attached to the object. Often useful for displaying to users.
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.
Purpose codes defined by the Financial Regulator for cross-border transactions.
curl -L -X POST 'https://api.xflowpay.com/v1/receivables' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"account_id": "account_F0A_1666079163481_A7fje_000",
"amount_maximum_reconcilable": "50.00",
"currency": "USD",
"invoice": {
"amount": "50.00",
"creation_date": "2022-10-18",
"currency": "USD",
"document": "file_F0A_1666079283600_ffoLd_000",
"due_date": "2022-11-07",
"reference_number": "Invoice FY 2022-23-038"
},
"purpose_code": "P1006",
"transaction_type": "services"
}'
Retrieve a Receivable
curl -L -X GET 'https://api.xflowpay.com/v1/receivables/receivable_f0A_1666079293438_eDQAH_000' \
-H 'Authorization: Bearer sk_your_key'
Update a Receivable
Maximum amount value that can be reconciled on this receivable.
The ISO 4217 3-digit code for the amount currency.
An arbitrary string attached to the object. Often useful for displaying to users.
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.
Purpose codes defined by the Financial Regulator for cross-border transactions.
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"
}
}'
List all Receivables
Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
The ISO 4217 3-digit code for the amount currency.
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.
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.
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.
draft The receivable is in draft state, and has not been submitted for verification.
verifying The receivable is being verified by the Xflow Operations team.
activated The receivable is activated, amount can be reconciled.
completed The receivable is completed, meaning amount_settled_payouts = amount_maximum_reconcilable.
cancelled The receivable is cancelled, amount can no longer be reconciled.
hold The receivable is being held due to (i) receivable verification process outcome (ii) associated partner or user in hold status or (iii) associated partner in deactivated status.
input_required The receivable requires input from the user.
curl -L -X GET 'https://api.xflowpay.com/v1/receivables?status=verifying' \
-H 'Authorization: Bearer sk_your_key'
Confirm a Receivable
curl -L -X POST 'https://api.xflowpay.com/v1/receivables/receivable_f0A_1666079293438_eDQAH_000/confirm' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json'
Cancel a Receivable
curl -L -X POST 'https://api.xflowpay.com/v1/receivables/receivable_f0A_1666079293438_eDQAH_000/cancel' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json'
Reconcile a Receivable
Unique identifier for the account object from which the funds for reconciliation are debited. This could be an account of type user or partner. If this parameter is not specified, Xflow will try to debit funds associated with the account of type partner for this receivable.
curl -L -X POST 'https://api.xflowpay.com/v1/receivables/receivable_f0A_1666079293438_eDQAH_000/reconcile' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"account_id": "account_F0A_1666184956871_JsBZ2_000",
"amount": "10.00"
}'
The Transfer object
The seconds elapsed since Unix epoch time at which the transfer object was created.
Details of the account and address from which the funds are being transferred.
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
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.
initialized The transfer object has been created but has not yet been processed.
processing The transfer object is now being processed.
completed The transfer object has completed successfully.
failed The transfer object has failed and funds if moved have been returned to the source.
cancelled The transfer object has cancelled by Xflow.
fee_advance_transfer This models a transfer of funds from one currency to another within the fee advance component of a platform.
internal_transfer This models a transfer of funds from a user to its partner, vice-versa and between user's partner's.
platform_credit This models a transfer of funds from a connected user to the platform. This transfer type is initiated by the platform.
platform_debit This models a transfer of funds from a platform to its connected user. This transfer type is initiated by the platform.
platform_fee_payout This indicates that the transfer is funded via credits for platform fees and debits for corresponding Xflow fees.
xflow_transfer This models a transfer of funds from or to an internal Xflow account.
{
"created": 1645104826,
"description": "Transfer for shortfall of USD",
"from": {
"account_id": null,
"amount": "123.40",
"currency": "USD"
},
"id": "transfer_f0A_1912224718366_laE3R_000",
"livemode": false,
"metadata": null,
"object": "transfer",
"status": "completed",
"to": {
"account_id": "account_f0A_1646922461210_p5A23_000",
"amount": "123.40",
"currency": "USD"
},
"type": "platform_fee_payout"
}
Create a Transfer
An arbitrary string attached to the object. Often useful for displaying to users.
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.
internal_transfer This models a transfer of funds from a user to its partner, vice-versa and between user's partner's.
platform_credit This models a transfer of funds from a connected user to the platform. This transfer type is initiated by the platform.
platform_debit This models a transfer of funds from a platform to its connected user. This transfer type is initiated by the platform.
curl -L -X POST https://api.xflowpay.com/v1/transfers \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"from": {
"account_id": "account_F0A_1666079163481_A7fje_000",
"amount": "123.40",
"currency": "USD"
},
"to": {
"account_id": "account_f0A_1646922461210_p5A23_000",
"currency": "USD"
},
"type": "internal_transfer"
}'
Retrieve a Transfer
curl -L -X GET 'https://api.xflowpay.com/v1/transfers/transfer_f0A_1912224718366_laE3R_000' \
-H 'Authorization: Bearer sk_your_key'
Update a Transfer
An arbitrary string attached to the object. Often useful for displaying to users.
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.
curl -L -X POST 'https://api.xflowpay.com/v1/transfers/transfer_f0A_1912224718366_laE3R_000' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"metadata": {
"internal_reference": "1234"
}
}'
List all Transfers
Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
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.
Account identifier for the account from which funds are being transferred. Refer account object for more details.
The ISO 4217 3-digit code for the source amount currency.
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.
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.
initialized The transfer object has been created but has not yet been processed.
processing The transfer object is now being processed.
completed The transfer object has completed successfully. Funds are now available in the to.currency.
failed The transfer object has failed and funds if moved have been returned to the source.
cancelled The transfer object has cancelled by Xflow.
Account identifier for the account to which funds are being transferred. Refer account object for more details.
The ISO 4217 3-digit code for the destination amount currency.
internal_transfer This models a transfer of funds from a user to its partner, vice-versa and between user's partner's.
platform_credit This models a transfer of funds from a connected user to the platform. This transfer type is initiated by the platform.
platform_debit This models a transfer of funds from a platform to its connected user. This transfer type is initiated by the platform.
platform_fee_payout This indicates that the transfer is funded via credits for platform fees and debits for corresponding Xflow fees.
xflow_transfer This models a transfer of funds from or to an internal Xflow account.
curl -L -X GET 'https://api.xflowpay.com/v1/transfers?status=completed' \
-H 'Authorization: Bearer sk_your_key'
WebhookEndpoints
You can configure webhook endpoints via the API to be notified about events that happen in your Xflow platform account, their connected accounts or in direct users (the latter is an Xflow account of type=user which is not connected to an account of type=platform).
Most users configure webhooks from the dashboard, which provides a user interface for registering and testing your webhook endpoints.
The WebhookEndpoint object
The seconds elapsed since Unix epoch time at which the WebhookEndpoint object was created.
The list of events to enable for this endpoint. [’*’] indicates that all events are enabled.
Has the value true if the object exists in livemode or the value false if the object exists in testmode.
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.
If true, the webhook endpoint will receive events for the platform. Else if false, the webhook endpoint will receive events for direct or connected users.
The endpoint’s secret, used to generate webhook signatures. In livemode, the secret is returned only as part of the create response and in testmode, the secret is always available on the object.
{
"created": 1662961392,
"description": "This is my webhook endpoint",
"enabled_events": [
"payout.status.settled",
"receivable.amount_settled_payouts.updated"
],
"id": "webhook_endpoint_f0A_1646921929908_lO60W_000",
"livemode": false,
"metadata": null,
"object": "webhook_endpoint",
"platform": true,
"secret": "webhook_secret_f0A_1646921929908_lO60W_000",
"status": "activated",
"url": "https://example.com/my/webhook/endpoint"
}
Create a WebhookEndpoint
An arbitrary string attached to the object. Often useful for displaying to users.
The list of events to enable for this endpoint. [’*’] indicates that all events are enabled, except those that require explicit selection.
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.
If true, the webhook endpoint will receive events for the platform. Else if false, the webhook endpoint will receive events for direct or connected users.
curl -L -X POST 'https://api.xflowpay.com/v1/webhook_endpoints' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d $'{
"description": "This is my webhook endpoint",
"enabled_events": [
"deposit.status.completed",
"payout.status.settled"
],
"platform": true,
"url": "https://example.com/my/webhook/endpoint"
}'
Retrieve a WebhookEndpoint
curl -L -X GET 'https://api.xflowpay.com/v1/webhook_endpoints/webhook_endpoint_f0A_1666184962045_5J7h9_000' \
-H 'Authorization: Bearer sk_your_key'
Update a WebhookEndpoint
An arbitrary string attached to the object. Often useful for displaying to users.
The list of events to enable for this endpoint. [’*’] indicates that all events are enabled.
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.
If true, the webhook endpoint will receive events for the platform. Else if false, the webhook endpoint will receive events for direct or connected users.
curl -L -X POST 'https://api.xflowpay.com/v1/webhook_endpoints/webhook_endpoint_f0A_1666184962045_5J7h9_000' \
-H 'Authorization: Bearer sk_your_key' \
-H 'Content-Type: application/json' \
-d '{
"metadata": {
"internal_reference": "ABC-1234"
}
}'
List all WebhookEndpoints
Return results where the created field is equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is greater than or equal to the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than the timestamp value in seconds elapsed since Unix epoch time.
Return results where the created field is lesser than or equal to the timestamp value in seconds elapsed since Unix epoch time.
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.
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.
If true, the response will contain webhook endpoints for platforms. Else if false, the response will contain webhook endpoints for direct users or connected users.
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.
curl -L -X GET 'https://api.xflowpay.com/v1/webhook_endpoints?limit=2&status=activated' \
-H 'Authorization: Bearer sk_your_key'