Overview
Assembly is a powerful payments engine custom-built for marketplaces. Removing compliance, fraud, risk, staffing, and operational headaches, Assembly helps online platforms focus on what matters most, their business.
Assembly supports international payments and multiple transaction types including escrow, partial release escrow and express payments. We also support a wide range of currencies.
Marketplaces can offer their buyers the ability to pay via Credit & Debit Cards, Wire Transfer, ACH, Direct Debit, BPAY, and PayPal (coming soon). Sellers can receive their funds either via ACH, PayPal, or Wire Transfer (international included).
Assembly provides you with an API to easily and quickly start taking payments on your marketplace.
Addresses
Addresses are associated with a User and Companies. The User Address is required for Users that are assigned as sellers, and is optional for buyers. If the User is a principal of a Company, then the Company Address is also required.
While an Address is optional for users set as buyers, it is recommended that you capture and create all Users with an Address, as they may at some stage be a seller on your marketplace or platform.
Show Address
Example Request
curl -X "GET" "https://test.api.promisepay.com/addresses/fe602dcf-4175-4f88-b5be-3beb04092dcd" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"addresses": {
"addressline1": "100 Main Street",
"addressline2": "",
"postcode": "2000",
"city": "Sydney",
"state": "NSW",
"id": "fe602dcf-4175-4f88-b5be-3beb04092dcd",
"country": "Australia",
"links": {
"self": "/addresses/fe602dcf-4175-4f88-b5be-3beb04092dcd"
}
}
}
Show details of a specific Address using a given :id.
Endpoint
GET /addresses/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | address ID |
Bank Accounts
Bank Accounts can be used as a funding source (Direct Debit/ACH) or as a Disbursement destination. Bank Accounts are associated with Users.
When creating a Bank Account, an :id is returned. You need to store the :id (and not the bank account details) against the user on your platform. When using a Bank Account as a funding source, the relevant :id is passed to the make_payment Item Action call. Additionally a Direct Debit Authority needs to be created in order for a Bank Account to be used as a funding source.
A Bank Account can also be set as a Disbursement destination. If set, the funds in a User’s Wallet Account will be disbursed to the Bank Account.
A Bank Account is required for all Users set as a seller even if they wish to use a PayPal Account as their Disbursement destination.
Penny credit verification is only supported for US platforms. When penny verification is enabled on a platform, it is required for all new bank accounts.
Create Bank Account
Example Request
client.bank_accounts.create(
user_id: '5830def0-ffe8-11e5-86aa-5e5517507c66',
bank_name: 'Bank of Australia',
account_name: 'Samuel Seller',
routing_number: '123123',
account_number: '12341234',
account_type: 'checking',
holder_type: 'personal',
country: 'AUS'
)
PromisePay::BankAccount()->create(array(
"user_id" => '5830def0-ffe8-11e5-86aa-5e5517507c66',
"bank_name" => 'Bank of Australia',
"account_name" => 'Samuel Seller',
"routing_number" => '123123',
"account_number" => '12341234',
"account_type" => 'checking',
"holder_type" => 'personal',
"country" => 'AUS',
));
var repo = container.Resolve<IBankAccountRepository>();
string promisePayUserID = dt.Rows[0]["pp_id"].ToString();
BankAccount account = new BankAccount
{
UserId = 5830def0-ffe8-11e5-86aa-5e5517507c66,
Active = true,
Bank = new Bank
{
BankName = "Bank of Australia",
AccountName = "Samuel Seller",
AccountNumber = "12341234",
AccountType = "checking",
Country = "AUS",
HolderType = "personal",
RoutingNumber = "123123"
}
};
var createdAccount = repo.CreateBankAccount(account);
curl -X "POST" "https://test.api.promisepay.com/bank_accounts" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"user_id\":\"5830def0-ffe8-11e5-86aa-5e5517507c66\",\"bank_name\":\"Bank of Australia\",\"account_name\":\"Samuel Seller\",\"routing_number\":\"123123\",\"account_number\":\"12341234\",\"account_type\":\"checking\",\"holder_type\":\"personal\",\"country\":\"AUS\",\"payout_currency\":\"AUD\"}"
Example Response (201)
{
"bank_accounts": {
"active": true,
"created_at": "2016-04-12T09:20:38.540Z",
"updated_at": "2016-04-12T09:20:38.540Z",
"id": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
"verification_status": "not_verified",
"currency": "AUD",
"bank": {
"bank_name": "Bank of Australia",
"country": "AUS",
"account_name": "Samuel Seller",
"routing_number": "XXXXX3",
"account_number": "XXX234",
"holder_type": "personal",
"account_type": "checking"
},
"links": {
"self": "/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
"users": "/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc/users"
}
}
}
Create a Bank Account to be used as either a funding source or a Disbursement destination.
Store the returned :id and use it for a make_payment Item Action call.
The :id is also referred to as a token when involving Bank Accounts.
Endpoint
POST /bank_accounts
Parameters
| Parameter | Type | Description |
|---|---|---|
| user_id required | String | user ID |
| bank_name required | String | bank name |
| account_name required | String | account name |
| routing_number required conditionally | String | routing number / SWIFT code / BSB number. See Bank account formats by country) |
| account_number required | String | account number / IBAN. See Bank account formats by country |
| account_type required | String | Bank Account Type (savings or checking) |
| holder_type required | String | Holder Type (personal or business) |
| country required | String | ISO 3166-1 alpha-3 country code (3 char) |
| currency | String | ISO 4217 alpha-3 currency code. This is an optional field and if not provided, the item will be created with the default currency of the marketplace |
| payout_currency | String | ISO 4217 alpha-3 currency code. This parameter determines the currency with which funds are paid out. |
Show Bank Account
Example Request
client.bank_accounts.find('46deb476-c1a6-41eb-8eb7-26a695bbe5bc')
PromisePay::BankAccount()->get('46deb476-c1a6-41eb-8eb7-26a695bbe5bc');
var repo = container.Resolve<IBankAccountRepository>();
repo.GetBankAccountById("46deb476-c1a6-41eb-8eb7-26a695bbe5bc");
curl -X "GET" "https://test.api.promisepay.com/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"bank_accounts": {
"id": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
"active": true,
"created_at": "2016-04-12T09:20:38.540Z",
"updated_at": "2016-04-13T14:22:40.674Z",
"verification_status": "not_verified",
"currency": "AUD",
"bank": {
"bank_name": "Bank of Australia",
"country": "AUS",
"account_name": "Samuel Seller",
"routing_number": "XXXXX3",
"account_number": "XXX234",
"holder_type": "personal",
"account_type": "checking",
"direct_debit_authority_status": "approved"
},
"links": {
"self": "/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
"users": "/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc/users",
"direct_debit_authorities": "/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc/direct_debit_authorities"
}
}
}
Show details of a specific Bank Account using a given :id.
Endpoint
GET /bank_accounts/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Bank account ID |
Redact Bank Account
Example Request
bank_account.deactivate(
id: '46deb476-c1a6-41eb-8eb7-26a695bbe5bc')
PromisePay::BankAccount()->delete('46deb476-c1a6-41eb-8eb7-26a695bbe5bc');
var repo = container.Resolve<IBankAccountRepository>();
repo.DeleteBankAccountById("46deb476-c1a6-41eb-8eb7-26a695bbe5bc");
curl -X "DELETE" "https://test.api.promisepay.com/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response
{
"bank_account": "Successfully redacted"
}
Redact a Bank Account using a given :id.
Redacted Bank Accounts can no longer be used as a funding source or a Disbursement destination.
Endpoint
DELETE /bank_accounts/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Bank account ID |
Show Bank Account User
Example Request
bank_account.user.find('46deb476-c1a6-41eb-8eb7-26a695bbe5bc')
PromisePay::BankAccount()->getUser('46deb476-c1a6-41eb-8eb7-26a695bbe5bc');
var repo = container.Resolve<IBankAccountRepository>();
repo.GetUserForBankAccountById("46deb476-c1a6-41eb-8eb7-26a695bbe5bc");
curl -X "GET" "https://test.api.promisepay.com/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc/users" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"users": {
"created_at": "2016-04-12T08:13:10.665Z",
"updated_at": "2016-04-12T08:13:10.665Z",
"full_name": "Samuel Seller",
"email": "samuel.seller@assemblypayments.com",
"mobile": "+61491570156",
"phone": null,
"logo_url": null,
"color_1": null,
"color_2": null,
"first_name": "Samuel",
"last_name": "Seller",
"id": "5830def0-ffe8-11e5-86aa-5e5517507c66",
"custom_descriptor": "Sam Garden Jobs",
"location": "AUS",
"verification_state": "pending",
"held_state": false,
"roles": [
"customer"
],
"dob": "encrypted",
"government_number": "encrypted",
"drivers_license": null,
"flags": {},
"related": {
"addresses": "fe602dcf-4175-4f88-b5be-3beb04092dcd",
"payout_account": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc"
},
"links": {
"self": "/bank_accounts/5830def0-ffe8-11e5-86aa-5e5517507c66/users",
"items": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/items",
"card_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/card_accounts",
"paypal_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/paypal_accounts",
"bank_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/bank_accounts",
"wallet_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/wallet_accounts"
}
}
}
Show the User the Bank Account is associated with using a given :id.
Endpoint
GET /bank_accounts/:id/users
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Bank account ID |
Validate Routing Number
Example Request
curl -X "GET" "https://test.api.promisepay.com/tools/routing_number" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"routing_number\":\"122235821\"}"
Example Response (200)
{
"routing_number": {
"routing_number": "122235821",
"customer_name": "US BANK NA",
"address": "EP-MN-WN1A",
"city": "ST. PAUL",
"state_code": "MN",
"zip": "55107",
"zip_extension": "1419",
"phone_area_code": "800",
"phone_prefix": "937",
"phone_suffix": "6310"
}
}
Validate a US bank routing number before creating an account. This can be used to provide on-demand verification, and further information of the bank information a User is providing.
Endpoint
GET /tools/routing_number
Parameters
| Parameter | Type | Description |
|---|---|---|
| routing_number | String | Bank account Routing Number |
Send Penny Amount
Example Request
curl -X "PATCH" "https://test.api.promisepay.com/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc/penny_send" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
Example Response (200)
{
"bank_accounts": {
"id": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
"active": true,
"created_at": "2016-04-12T09:20:38.540Z",
"updated_at": "2016-04-13T14:22:40.674Z",
"verification_status": "verifying",
"currency": "AUD",
"bank": {
"bank_name": "Bank of Australia",
"country": "AUS",
"account_name": "Samuel Seller",
"routing_number": "XXXXX3",
"account_number": "XXX234",
"holder_type": "personal",
"account_type": "checking",
"direct_debit_authority_status": "approved"
},
"links": {
"self": "/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
"users": "/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc/users",
"direct_debit_authorities": "/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc/direct_debit_authorities"
}
}
}
When penny verification is enabled, this API call sends two penny transactions to the specified bank account for verification.
Note: This API call is not required when your platform has automatic penny verification enabled, as this is instead done by the system. Penny credit verification is only supported for US platforms.
Endpoint
PATCH /bank_accounts/:id/penny_send
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | Bank account ID |
Verify Penny Amount
Example Request
curl -X "PATCH" "https://test.api.promisepay.com/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc/penny_verify" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"amount_1\":\"0015\",\"amount_2\":\"0007\"}"
Example Response (200)
{
"bank_accounts": {
"id": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
"active": true,
"created_at": "2016-04-12T09:20:38.540Z",
"updated_at": "2016-04-13T14:22:40.674Z",
"verification_status": "verified",
"currency": "AUD",
"bank": {
"bank_name": "Bank of Australia",
"country": "AUS",
"account_name": "Samuel Seller",
"routing_number": "XXXXX3",
"account_number": "XXX234",
"holder_type": "personal",
"account_type": "checking",
"direct_debit_authority_status": "approved"
},
"links": {
"self": "/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc/penny_verify?amount_1=0015&amount_2=0007",
"users": "/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc/users",
"direct_debit_authorities": "/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc/direct_debit_authorities"
}
}
}
When penny verification is enabled, this API call verifies the two penny transactions that were sent to a specified bank account using Send Penny Amount
Note: This API call requires you to provide a front-end interface to your end-users into which they can input the penny amounts required for a successful verification. Your front-end interface should then pass the information into this API call. Penny credit verification is only supported for US platforms.
Endpoint
PATCH /bank_accounts/:id/penny_verify
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | Bank account ID |
| amount_1 | integer | first penny amount in cents; can range from 1 to 30 cents |
| amount_2 | integer | second penny amount in cents; can range from 1 to 30 cents |
Card Accounts
Card Accounts can be used as a funding source. Card Accounts are associated with Users.
When creating a Card Account, a token is returned. You need to store the :id (and not the credit card account details) against the user on your platform. When using a Card Account as a funding source, the :id is passed to the make_payment Item Action.
There are PCI requirements for protecting Credit Card Account data.
Create Card Account
Example Request
client.card_accounts.create(
user_id: '064d6800-fff3-11e5-86aa-5e5517507c66',
full_name: 'Bella Buyer',
number: '4111111111111111',
expiry_month: '10',
expiry_year: '2020',
cvv: '123'
)
PromisePay::CardAccount()->create(array(
"user_id" => '064d6800-fff3-11e5-86aa-5e5517507c66',
"full_name" => 'Bella Buyer',
"number" => '4111111111111111',
"expiry_month" => '10',
"expiry_year" => '2020',
"cvv" => '123'
));
var repo = container.Resolve<ICardAccountRepository>();
repo.CreateCardAccount(new Dictionary<string, object>{
{"user_id", "064d6800-fff3-11e5-86aa-5e5517507c66"},
{"full_name", "Bella Buyer"},
{"number", "4111111111111111"},
{"expiry_month", "10"}
{"expiry_year", "2020"},
{"cvv", "123"},
});
curl -X "POST" "https://test.api.promisepay.com/card_accounts" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"full_name\":\"Bella Buyer\",\"number\":\"4111111111111111\",\"expiry_month\":\"10\",\"expiry_year\":\"2020\",\"cvv\":\"123\",\"user_id\":\"064d6800-fff3-11e5-86aa-5e5517507c66\",\"currency\":\"AUD\"}"
Example Response (201)
{
"card_accounts": {
"active": true,
"created_at": "2016-04-13T02:59:39.048Z",
"updated_at": "2016-04-13T02:59:39.048Z",
"id": "930a7f78-6bf6-4f33-8cfc-b82c787b5f83",
"currency": "AUD",
"links": {
"self": "/card_accounts/930a7f78-6bf6-4f33-8cfc-b82c787b5f83",
"users": "/card_accounts/930a7f78-6bf6-4f33-8cfc-b82c787b5f83/users"
}
}
}
Create a Credit Card Account to be used as a funding source.
Store the returned :id and use it for a make_payment Item Action call.
The :id is also referred to as a token when involving Credit Cards.
Endpoint
POST /card_accounts
Parameters
| Parameter | Type | Description |
|---|---|---|
| user_id required | String | user ID |
| full_name required | String | user full name with atleast a space |
| number required | String | account number |
| expiry_month required | Integer | expiry month (mm) |
| expiry_year required | Integer | expiry year (yyyy) |
| cvv required | String | cvv/cvc |
Show Card Account
Example Request
client.card_accounts.find('930a7f78-6bf6-4f33-8cfc-b82c787b5f83')
PromisePay::CardAccount()->get('930a7f78-6bf6-4f33-8cfc-b82c787b5f83');
var repo = container.Resolve<ICardAccountRepository>();
repo.GetCardAccountById("930a7f78-6bf6-4f33-8cfc-b82c787b5f83");
curl -X "GET" "https://test.api.promisepay.com/card_accounts/930a7f78-6bf6-4f33-8cfc-b82c787b5f83" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
Example Response (200)
{
"card_accounts": {
"active": true,
"created_at": "2016-04-13T02:59:39.048Z",
"updated_at": "2016-04-13T02:59:39.048Z",
"id": "930a7f78-6bf6-4f33-8cfc-b82c787b5f83",
"currency": "AUD",
"card": {
"type": "visa",
"full_name": "Bella Buyer",
"number": "XXXX-XXXX-XXXX-1111",
"expiry_month": "10",
"expiry_year": "2020"
},
"links": {
"self": "/card_accounts/930a7f78-6bf6-4f33-8cfc-b82c787b5f83",
"users": "/card_accounts/930a7f78-6bf6-4f33-8cfc-b82c787b5f83/users"
}
}
}
Show details of a specific Credit Card Account using a given :id.
You can toggle the card account number display to show the first 6 digits in addition to the last 4 digits. Contact Assembly if you want to toggle the card account display.
Endpoint
GET /card_accounts/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Card account ID |
Redact Card Account
Example Request
card_account.deactivate(
id: '930a7f78-6bf6-4f33-8cfc-b82c787b5f83')
PromisePay::CardAccount()->delete('930a7f78-6bf6-4f33-8cfc-b82c787b5f83');
var repo = container.Resolve<ICardAccountRepository>();
repo.DeleteCardAccountById("930a7f78-6bf6-4f33-8cfc-b82c787b5f83");
curl -X "DELETE" "https://test.api.promisepay.com/card_accounts/930a7f78-6bf6-4f33-8cfc-b82c787b5f83" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response
{
"card_account": "Successfully redacted"
}
Redact a Credit Card Account using a given :id.
Redacted Credit Card Accounts can no longer be used as a funding source.
Endpoint
DELETE /card_accounts/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Card account ID |
Show Card Account User
Example Request
card_account.user.find('930a7f78-6bf6-4f33-8cfc-b82c787b5f83')
PromisePay::CardAccount()->getUser('930a7f78-6bf6-4f33-8cfc-b82c787b5f83');
var repo = container.Resolve<ICardAccountRepository>();
repo.GetUserForCardAccountById("930a7f78-6bf6-4f33-8cfc-b82c787b5f83");
curl -X "GET" "https://test.api.promisepay.com/card_accounts/930a7f78-6bf6-4f33-8cfc-b82c787b5f83/users" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
Example Response (200)
{
"users": {
"created_at": "2016-04-12T08:10:47.458Z",
"updated_at": "2016-04-12T08:10:47.458Z",
"full_name": "Bella Buyer",
"email": "bella.buyer@example.com",
"mobile": "+61491570159",
"phone": null,
"logo_url": null,
"color_1": null,
"color_2": null,
"first_name": "Bella",
"last_name": "Buyer",
"id": "064d6800-fff3-11e5-86aa-5e5517507c66",
"custom_descriptor": null,
"location": "AUS",
"verification_state": "approved",
"held_state": false,
"roles": [
"customer"
],
"dob": "encrypted",
"government_number": "encrypted",
"drivers_license": null,
"flags": {},
"related": {
"addresses": "d2b7dcea-0a4e-4ce4-9259-982619d90ad4",
"payout_account": "5019f85d-dca4-4766-a737-033d81e046c5"
},
"links": {
"self": "/card_accounts/930a7f78-6bf6-4f33-8cfc-b82c787b5f83/users",
"items": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/items",
"card_accounts": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/card_accounts",
"paypal_accounts": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/paypal_accounts",
"bank_accounts": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/bank_accounts",
"wallet_accounts": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/wallet_accounts"
}
}
}
Show the User the Credit Card Account is associated with using a given :id.
Endpoint
GET /card_accounts/:id/users
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Card account ID |
Verify Card
Example Request
curl -X "PATCH" "https://test.api.promisepay.com/card_accounts/930a7f78-6bf6-4f33-8cfc-b82c787b5f83/verify" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
Example Response (200)
{
"card_accounts": {
"active": true,
"created_at": "2016-04-13T02:59:39.048Z",
"updated_at": "2016-04-13T02:59:39.048Z",
"id": "930a7f78-6bf6-4f33-8cfc-b82c787b5f83",
"verification_status": "verified",
"currency": "AUD",
"card": {
"type": "visa",
"full_name": "Bella Buyer",
"number": "XXXX-XXXX-XXXX-1111",
"expiry_month": "10",
"expiry_year": "2020"
},
"links": {
"self": "/card_accounts/930a7f78-6bf6-4f33-8cfc-b82c787b5f83/verify",
"users": "/card_accounts/930a7f78-6bf6-4f33-8cfc-b82c787b5f83/users"
}
}
}
Where pre-authentication is enabled on a platform, verifies a Card Account When a Card Account is successfully verified, its verification status is verified.
Endpoint
PATCH /card_accounts/:id/verify
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Card account ID |
PayPal Accounts
PayPal Accounts are associated with Users and can be used as a Disbursement destination.
Create PayPal Account
Example Request
client.paypal_accounts.create(
user_id: '5830def0-ffe8-11e5-86aa-5e5517507c66',
paypal_email: 'samuel.seller@promisepay.com',
)
PromisePay::PayPalAccount()->create(array(
"user_id" => '5830def0-ffe8-11e5-86aa-5e5517507c66',
"paypal_email" => 'samuel.seller@promisepay.com'
));
var repo = container.Resolve<IPayPalAccountRepository>();
repo.CreatePayPalAccount(new Dictionary<string,object>{
{"user_id", "5830def0-ffe8-11e5-86aa-5e5517507c66"},
{"paypal_email", "samuel.seller@promisepay.com"},
});
curl -X "POST" "https://test.api.promisepay.com/paypal_accounts" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"user_id\":\"5830def0-ffe8-11e5-86aa-5e5517507c66\",\"paypal_email\":\"samuel.seller@promisepay.com\"}"
Example Response (201)
{
"paypal_accounts": {
"active": true,
"created_at": "2016-04-13T06:33:21.633Z",
"updated_at": "2016-04-13T06:33:21.633Z",
"id": "7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b",
"currency": "AUD",
"paypal": {
"email": "samuel.seller@assemblypayments.com"
},
"links": {
"self": "/paypal_accounts/7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b",
"users": "/paypal_accounts/7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b/users"
}
}
}
Create a PayPal Account to be used as a Disbursement destination.
Endpoint
POST /paypal_accounts
Parameters
| Parameter | Type | Description |
|---|---|---|
| user_id | String | user ID |
| paypal_email | String | paypal email address |
| pay_in | String |
Show PayPal Account
Example Request
client.paypal_accounts.find('7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b')
PromisePay::PayPalAccount()->get('7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b');
var repo = container.Resolve<IPayPalAccountRepository>();
repo.GetPayPalAccountById("7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b");
curl -X "GET" "https://test.api.promisepay.com/paypal_accounts/7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"paypal_accounts": {
"active": true,
"created_at": "2016-04-13T06:33:21.633Z",
"updated_at": "2016-04-13T06:33:21.633Z",
"id": "7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b",
"currency": "AUD",
"paypal": {
"email": "samuel.seller@assemblypayments.com"
},
"links": {
"self": "/paypal_accounts/7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b",
"users": "/paypal_accounts/7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b/users"
}
}
}
Show details of a specific PayPal Account using a given :id.
Endpoint
GET /paypal_accounts/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | PayPal account ID |
Redact PayPal Account
Example Request
paypal_account.deactivate(
id: '7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b')
PromisePay::PayPalAccount()->delete('7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b');
var repo = container.Resolve<IPayPalAccountRepository>();
repo.DeletePayPalAccountById("7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b");
curl -X "DELETE" "https://test.api.promisepay.com/paypal_accounts/7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response
{
"paypal_account": "Successfully redacted"
}
Redact a PayPal Account using a given :id.
Redacted PayPal Accounts can no longer be used as a Disbursement destination.
Endpoint
DELETE /paypal_accounts/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | PayPal account ID |
Show PayPal Account User
Example Request
paypal_account.user,find('7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b')
PromisePay::PayPalAccount()->getUser('7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b');
var repo = container.Resolve<IPayPalAccountRepository>();
repo.GetUserForPayPalAccountById("7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b");
curl -X "GET" "https://test.api.promisepay.com/paypal_accounts/7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b/users" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"users": {
"created_at": "2016-04-12T08:13:10.665Z",
"updated_at": "2016-04-12T08:13:10.665Z",
"full_name": "Samuel Seller",
"email": "samuel.seller@assemblypayments.com",
"mobile": "+61491570156",
"phone": null,
"logo_url": null,
"color_1": null,
"color_2": null,
"first_name": "Samuel",
"last_name": "Seller",
"id": "5830def0-ffe8-11e5-86aa-5e5517507c66",
"custom_descriptor": "Sam Garden Jobs",
"location": "AUS",
"verification_state": "pending",
"held_state": false,
"roles": [
"customer"
],
"dob": "encrypted",
"government_number": "encrypted",
"drivers_license": null,
"flags": {},
"related": {
"addresses": "fe602dcf-4175-4f88-b5be-3beb04092dcd",
"payout_account": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc"
},
"links": {
"self": "/paypal_accounts/5830def0-ffe8-11e5-86aa-5e5517507c66/users",
"items": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/items",
"card_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/card_accounts",
"paypal_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/paypal_accounts",
"bank_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/bank_accounts",
"wallet_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/wallet_accounts"
}
}
}
Show the User the PayPal Account is associated with using a given :id.
Endpoint
GET /paypal_accounts/:id/users
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | PayPal account ID |
Charges
Charges allow you to easily charge a Card Account or Bank Account in a single call. A Charge combines the functionality of an Account, Item and User. A Charge will be sent directly to the Platform, not to a specified Seller. If you wish to accept and disburse funds between 2 Users, you will need to use the Items API.
Create Charge
Example Request
client.charges.create(
account_id: 'b49d943f-add0-4d1c-b357-0f1a8fde677c',
name: 'Charge for Delivery',
amount: 4500,
email: 'anonymous+buyer+1@assemblypayments.com',
zip: 3000,
country: 'AUS',
currency: 'AUD',
retain_account: true,
)
PromisePay::Charges()->create(array(
"account_id" => 'b49d943f-add0-4d1c-b357-0f1a8fde677c',
"name" => 'Charge for Delivery',
"amount" => 4500,
"email" => 'anonymous+buyer+1@assemblypayments.com',
"zip" => 3000,
"country" => 'AUS',
"currency" => 'AUD',
"retain_account" => true,
));
var repo = container.Resolve<IChargeRepository>();
repo.CreateCharge(new Dictionary<string, object>
{"account_id", "b49d943f-add0-4d1c-b357-0f1a8fde677c"},
{"name", "Charge for Delivery"},
{"amount", 4500},
{"email", "anonymous+buyer+1@assemblypayments.com"},
{"zip" 3000},
{"country", "AUS"},
{"currency", "AUD"},
{"retain_account", true},
});
curl -X "POST" "https://test.api.promisepay.com/charges" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"account_id\":\"b49d943f-add0-4d1c-b357-0f1a8fde677c\",\"name\":\"Charge for Delivery\",\"amount\":\"4500\",\"email\":\"anonymous+buyer+1@promisepay.com\",\"zip\":\"3000\",\"currency\":\"AUD\",\"country\":\"AUS\",\"retain_account\":true,\"}"
Example Response (201)
{
"charges": {
"id": "cb7eafc1-571c-425c-9adc-f56cb585cd68",
"name": "Charge for Delivery",
"created_at": "2016-06-10T07:30:10.554Z",
"updated_at": "2016-06-10T07:30:17.350Z",
"state": "completed",
"buyer_fees": 0,
"seller_fees": 0,
"credit_card_fee": 0,
"status": 22500,
"amount": 4500,
"custom_descriptor": null,
"custom_data": null,
"account_id": "b49d943f-add0-4d1c-b357-0f1a8fde677c",
"account_type": "credit card",
"promisepay_fee": 187,
"currency": "AUD",
"payment_method": "charge",
"dynamic_descriptor": "ASM*Samuel Seller",
"buyer_name": "Anonymous Buyer",
"buyer_email": "anonymous+buyer+1@assemblypayments.com",
"buyer_zip": "3000",
"buyer_country": "AUS",
"related": {
"buyers": "1be7f54f-c09f-4298-a665-f3a9f1dac60c",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/charges",
"buyers": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/buyers",
"sellers": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/sellers",
"status": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/status",
"fees": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/fees",
"transactions": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/transactions",
"batch_transactions": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/batch_transactions"
}
}
}
Create a Charge. Charges require a specified Card Account or Bank Account. You may pass through an existing User, or define the user_id of the new user that will be associated with the Charge and the provided Account.
The user_id can be left blank if you wish for a new user to be created for the Charge, or specified if you wish for a new User to be created with the passed user_id.
Endpoint
POST /charges
Parameters
| Parameter | Type | Description |
|---|---|---|
| account_id required | String | Bank Account or Card Account ID |
| name | String | Name |
| amount required | String | The cost being charged in cents. |
| name | String | Description of the Charge being created. |
| email required | String | Email of the user associated with the account being charged. |
| zip required | Integer | Postcode. |
| country required | String | ISO 3166-1 alpha-3 country code of the User being charged. |
| user_id | String | The ID of the User |
| fee_ids | String | A comma separated list of fee ID’s to apply |
| currency | String | ISO 4217 alpha-3 currency code. This is an optional field and if not provided, the item will be created with the default currency of the marketplace |
| retain_account | Boolean | True - Enables the account to be charged in the future. False - Redacts the account after this charge. |
| device_id | String | Device Information provided by Assembly client-side SDKs |
| ip_address | String | IP Information provided by Assembly client-side SDKs |
| custom_descriptor | String | When custom_descriptors are enabled, this is the information to appear on credit card and direct debit statements. |
List Charges
Example Request
client.charges.find_all
PromisePay::Charges()->getList();
var repo = container.Resolve<IChargeRepository>();
repo.ListCharges();
curl -X "GET" "https://test.api.promisepay.com/charges" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"charges": [
{
"id": "cb7eafc1-571c-425c-9adc-f56cb585cd68",
"name": "Charge for Delivery",
"created_at": "2016-06-10T07:30:10.554Z",
"updated_at": "2016-06-10T07:30:17.350Z",
"state": 22500,
"buyer_fees": 0,
"seller_fees": 0,
"credit_card_fee": 0,
"status": 22500,
"amount": 4500,
"custom_descriptor": null,
"custom_data": null,
"account_id": "b49d943f-add0-4d1c-b357-0f1a8fde677c",
"account_type": "credit card",
"promisepay_fee": 187,
"currency": "AUD",
"payment_method": "charge",
"dynamic_descriptor": "ASM*Samuel Seller",
"buyer_name": "Anonymous Buyer",
"buyer_email": "anonymous+buyer+1@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"links": {
"self": "/charges",
"buyers": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/buyers",
"sellers": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/sellers",
"status": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/status",
"fees": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/fees",
"transactions": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/transactions",
"batch_transactions": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/batch_transactions"
}
}
],
"links": {
"self": "/charges"
},
"meta": {
"limit": 10,
"offset": 0,
"total": 1
}
}
Retrieve an ordered and paginated list of existing Charges.
Endpoint
GET /charges
Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | Integer | Number of records to retrieve. Up to 200. |
| offset | Integer | Number of records to offset. Required for pagination. |
Show Charge
Example Request
client.charges.find('cb7eafc1-571c-425c-9adc-f56cb585cd68')
PromisePay::Charges()->get('cb7eafc1-571c-425c-9adc-f56cb585cd68');
var repo = container.Resolve<IChargeRepository>();
repo.GetChargeById("cb7eafc1-571c-425c-9adc-f56cb585cd68");
curl -X "GET" "https://test.api.promisepay.com/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"charges": {
"id": "cb7eafc1-571c-425c-9adc-f56cb585cd68",
"name": "Charge for Delivery",
"created_at": "2016-06-10T07:30:10.554Z",
"updated_at": "2016-06-10T07:30:17.350Z",
"state": "completed",
"buyer_fees": 0,
"seller_fees": 0,
"credit_card_fee": 0,
"status": 22500,
"amount": 4500,
"custom_descriptor": null,
"custom_data": null,
"account_id": "b49d943f-add0-4d1c-b357-0f1a8fde677c",
"account_type": "credit card",
"promisepay_fee": 187,
"currency": "AUD",
"payment_method": "charge",
"dynamic_descriptor":"ASM*Samuel Seller",
"buyer_name": "Anonymous Buyer",
"buyer_email": "anonymous+buyer+1@assemblypayments.com",
"buyer_zip": "3000",
"buyer_country": "AUS",
"related": {
"buyers": "1be7f54f-c09f-4298-a665-f3a9f1dac60c",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68",
"buyers": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/buyers",
"sellers": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/sellers",
"status": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/status",
"fees": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/fees",
"transactions": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/transactions",
"batch_transactions": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/batch_transactions"
}
}
}
Show details of a specific Charge using a given :id.
Endpoint
GET /charges/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Charge ID |
Show Charge Buyer
Example Request
charges.buyer.find('cb7eafc1-571c-425c-9adc-f56cb585cd68')
PromisePay::Charges()->getBuyer('cb7eafc1-571c-425c-9adc-f56cb585cd68');
var repo = container.Resolve<IChargeRepository>();
repo.GetChargeBuyerById("cb7eafc1-571c-425c-9adc-f56cb585cd68");
curl -X "GET" "https://test.api.promisepay.com/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/buyers" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"users": {
"created_at": "2016-06-10T07:30:10.014Z",
"updated_at": "2016-06-10T07:30:10.669Z",
"full_name": "Anonymous Buyer",
"email": "anonymous+buyer+1@assemblypayments.com",
"mobile": null,
"phone": null,
"logo_url": null,
"color_1": null,
"color_2": null,
"first_name": "Anonymous",
"last_name": "Buyer",
"id": "1be7f54f-c09f-4298-a665-f3a9f1dac60c",
"custom_descriptor": null,
"location": "AUS",
"verification_state": "pending",
"held_state": false,
"roles": [
"customer"
],
"dob": null,
"government_number": null,
"drivers_license": null,
"flags": {},
"related": {
"addresses": "9e2f1a34-3be0-4917-b27d-d6215cb164b3"
},
"links": {
"self": "/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/buyers",
"items": "/users/1be7f54f-c09f-4298-a665-f3a9f1dac60c/items",
"card_accounts": "/users/1be7f54f-c09f-4298-a665-f3a9f1dac60c/card_accounts",
"paypal_accounts": "/users/1be7f54f-c09f-4298-a665-f3a9f1dac60c/paypal_accounts",
"bank_accounts": "/users/1be7f54f-c09f-4298-a665-f3a9f1dac60c/bank_accounts",
"wallet_accounts": "/users/1be7f54f-c09f-4298-a665-f3a9f1dac60c/wallet_accounts"
}
}
}
Show the buyer User associated with the Charge using a given :id.
Endpoint
GET /charges/:id/buyers
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Charge ID |
Show Charge Status
Example Request
charges.status.find('cb7eafc1-571c-425c-9adc-f56cb585cd68')
PromisePay::Charges()->getStatus('cb7eafc1-571c-425c-9adc-f56cb585cd68');
var repo = container.Resolve<IChargeRepository>();
repo.GetChargeStatusById("cb7eafc1-571c-425c-9adc-f56cb585cd68");
curl -X "GET" "https://test.api.promisepay.com/charges/cb7eafc1-571c-425c-9adc-f56cb585cd68/status" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"charges": {
"id": "cb7eafc1-571c-425c-9adc-f56cb585cd68",
"status": 22500,
"state": "completed"
}
}
Show details of a specific Charge using a given :id.
Endpoint
GET /charges/:id/status
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Charge ID |
Batch Transactions
Batch Transactions allow you to view the status of batched funds, inbound or outbound. Transactions are batched when using a Bank Account to fund an Item, or when disbursing funds to a Bank Account or PayPal Account.
List Batch Transactions
Example Request
client.batch_transactions.find_all
curl -X "GET" "https://test.api.promisepay.com/batch_transactions" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"batch_transactions": [
{
"id": "4098c6fd-ca04-4e0d-9454-87def4523a23",
"created_at": "2016-04-18T08:15:02.780Z",
"updated_at": "2016-04-18T08:15:02.780Z",
"type": "misc",
"type_method": "misc",
"batch_id": 302,
"reference": null,
"state": "batched",
"user_id": "064d6800-fff3-11e5-86aa-5e5517507c66",
"account_id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"account_type": "item",
"amount": 24500,
"currency": "AUD",
"debit_credit": "credit",
"description": "Credit of $245.00 to Item by Debit of $245.00 from Wallet Account",
"related": {
"account_to": {
"id": "385b50bb-237a-42cb-9382-22953e191ae6",
"account_type": "wallet_account",
"user_id": "5830def0-ffe8-11e5-86aa-5e5517507c66"
}
}
},
{
"id": "b1652611-9544-4244-a601-54c24cfa5e90",
"created_at": "2016-04-18T08:20:20.354Z",
"updated_at": "2016-04-18T08:20:20.354Z",
"type": "misc",
"type_method": "misc",
"batch_id": 302,
"reference": null,
"state": "batched",
"user_id": "064d6800-fff3-11e5-86aa-5e5517507c66",
"account_id": "e57120ea-053d-11e6-b512-3e1d05defe78",
"account_type": "item",
"amount": 9800,
"currency": "AUD",
"debit_credit": "credit",
"description": "Credit of $98.00 to Item by Debit of $98.00 from Wallet Account",
"related": {
"account_to": {
"id": "385b50bb-237a-42cb-9382-22953e191ae6",
"account_type": "wallet_account",
"user_id": "5830def0-ffe8-11e5-86aa-5e5517507c66"
}
}
}
],
"meta": {
"limit": 10,
"offset": 0,
"total": 2
},
"links": {
"self": "/batch_transactions"
}
}
Retrieve an ordered and paginated list of existing Batch Transactions.
The list can be filtered by Account, Batch ID, Item, and Transaction Type.
Endpoint
GET /batch_transactions
Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | Integer | Number of records to retrieve. Up to 200. |
| offset | Integer | Number of records to offset. Required for pagination. |
| account_id | Integer | Bank, Card, PayPal or Wallet Account ID. |
| batch_id | Integer | Batch ID. This appears on a bank reference. |
| item_id | Integer | Item ID. |
| transaction_type | String | The type of transaction. Options: payment, refund, disbursement, fee, deposit, withdrawal. |
| transaction_type_method | The method the transaction was carried out with. Options: bundle_direct_debit, direct_debit, credit_card, wire_transfer, direct_credit, paypal_payout. | |
| direction | String | Direction of the transaction. Options: debit, credit. |
Show Batch Transaction
Example Request
client.batch_transactions.find('b1652611-9544-4244-a601-54c24cfa5e90')
curl -X "GET" "https://test.api.promisepay.com/batch_transactions/b1652611-9544-4244-a601-54c24cfa5e90" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"batch_transactions": {
"id": "b1652611-9544-4244-a601-54c24cfa5e90",
"created_at": "2016-04-18T08:20:20.354Z",
"updated_at": "2016-04-18T08:20:20.354Z",
"type": "misc",
"type_method": "misc",
"batch_id": 302,
"reference": null,
"state": "batched",
"user_id": "064d6800-fff3-11e5-86aa-5e5517507c66",
"account_id": "e57120ea-053d-11e6-b512-3e1d05defe78",
"account_type": "item",
"amount": 9800,
"currency": "AUD",
"debit_credit": "credit",
"description": "Credit of $98.00 to Item by Debit of $98.00 from Wallet Account",
"related": {
"account_to": {
"id": "385b50bb-237a-42cb-9382-22953e191ae6",
"account_type": "wallet_account",
"user_id": "5830def0-ffe8-11e5-86aa-5e5517507c66"
}
},
"links": {
"self": "/batch_transactions/b1652611-9544-4244-a601-54c24cfa5e90",
"users": "/transactions/b1652611-9544-4244-a601-54c24cfa5e90/users",
"fees": "/transactions/b1652611-9544-4244-a601-54c24cfa5e90/fees",
"wallet_accounts": "/transactions/b1652611-9544-4244-a601-54c24cfa5e90/wallet_accounts",
"card_accounts": "/transactions/b1652611-9544-4244-a601-54c24cfa5e90/card_accounts",
"paypal_accounts": "/transactions/b1652611-9544-4244-a601-54c24cfa5e90/paypal_accounts",
"bank_accounts": "/transactions/b1652611-9544-4244-a601-54c24cfa5e90/bank_accounts",
"items": "/transactions/b1652611-9544-4244-a601-54c24cfa5e90/items"
}
}
}
Show details of a specific Batch Transaction using a given :id.
Endpoint
GET /batch_transactions/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Transaction ID |
Callbacks
Callbacks are a useful way of notifying you when an object changes. For example: if an Item changes state because we have processed an Direct Debit/ACH payment, we will post a JSON payload with the Item object attributes to the URL provided.
Only one Callback can be enabled for an object type (Items, Users, Companies, Addresses, Accounts, Disbursements, Transactions and Batch Transactions).
Only HTTPS URLs are supported and it requires a valid SSL certificate. Self-signed certificates are not supported.
When creating a Callback the URL provided will be sent a test JSON payload and will only be successfully created if we receive a non 500 response.
json { “message”: “Assembly callback test” }
Create Callback
Example Request
curl -X "POST" "https://test.api.promisepay.com/callbacks" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"description\":\"Users Callback\",\"url\":\"https://httpbin.org/post\",\"object_type\":\"users\",\"enabled\":\"true\"}"
Example Response (201)
{
"callbacks": {
"id": "f92d4ca1-4ee5-43f3-9e34-ca5f759c5e76",
"description": "Users Callback",
"url": "https://httpbin.org/post",
"object_type": "users",
"enabled": true,
"created_at": "2016-04-18T00:26:45.913Z",
"updated_at": "2016-04-18T00:26:45.913Z",
"links": {
"self": "/callbacks",
"responses": "/callbacks/f92d4ca1-4ee5-43f3-9e34-ca5f759c5e76/responses"
}
}
}
Create a Callback to notify you at the URL when the object_type changes
Endpoint
POST /callbacks
Parameters
| Parameter | Type | Description |
|---|---|---|
| description | string | description to identify the callback |
| url | string | URL to which the callbacks will notify |
| object_type | string | object or entity to which the callbacks refer |
| enabled | string | toggle whether callback is active or inactive |
List Callbacks
Example Request
curl -X "GET" "https://test.api.promisepay.com/callbacks" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"limit\":\"\",\"offset\":\"\",\"filter\":\"\"}"
Example Response (200)
{
"callbacks": [
{
"id": "f92d4ca1-4ee5-43f3-9e34-ca5f759c5e76",
"created_at": "2016-04-18T00:26:45.913Z",
"updated_at": "2016-04-18T00:26:45.913Z",
"description": "Users Callback",
"url": "https://httpbin.org/post",
"object_type": "users",
"enabled": true
}
],
"meta": {
"limit": 10,
"offset": 0,
"total": 1
},
"links": {
"self": "/callbacks"
}
}
Retrieve an ordered and paginated list of all created Callbacks.
Endpoint
GET /callbacks
Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Number of records to retrieve (up to 200) |
| offset | integer | Number of records to offset for pagination |
| filter | string | narrow down records to relevant character string |
Show Callback
Example Request
curl -X "GET" "https://test.api.promisepay.com/callbacks/f92d4ca1-4ee5-43f3-9e34-ca5f759c5e76" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"callbacks": {
"id": "f92d4ca1-4ee5-43f3-9e34-ca5f759c5e76",
"description": "Users Callback",
"url": "https://httpbin.org/post",
"object_type": "users",
"enabled": true,
"created_at": "2016-04-18T00:26:45.913Z",
"updated_at": "2016-04-18T00:26:45.913Z",
"links": {
"self": "/callbacks/f92d4ca1-4ee5-43f3-9e34-ca5f759c5e76",
"responses": "/callbacks/f92d4ca1-4ee5-43f3-9e34-ca5f759c5e76/responses"
}
}
}
Show details of a specific Callback using a given :id.
Endpoint
GET /callbacks/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | callback ID |
Update Callback
Example Request
curl -X "PATCH" "https://test.api.promisepay.com/callbacks/f92d4ca1-4ee5-43f3-9e34-ca5f759c5e76" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"description\":\"Users Callback\",\"url\":\"https://httpbin.org/post\",\"object_type\":\"users\",\"enabled\":\"true\"}"
Example Response (200)
{
"callbacks": {
"id": "f92d4ca1-4ee5-43f3-9e34-ca5f759c5e76",
"description": "Users Callback",
"url": "https://httpbin.org/post",
"object_type": "users",
"enabled": true,
"created_at": "2016-04-18T00:26:45.913Z",
"updated_at": "2016-04-18T00:26:45.913Z",
"links": {
"self": "/callbacks/f92d4ca1-4ee5-43f3-9e34-ca5f759c5e76",
"responses": "/callbacks/f92d4ca1-4ee5-43f3-9e34-ca5f759c5e76/responses"
}
}
}
Update an existing Callback using a given :id.
You can change the URL, the object_type and whether the Callback is enabled or disabled.
Endpoint
PATCH /callbacks/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | callback id |
| description | string | description to identify the callback |
| url | string | URL to which the callbacks will notify |
| object_type | string | object or entity to which the callbacks refer |
| enabled | string | toggle whether callback is active or inactive |
Delete Callback
Example Request
curl -X "DELETE" "https://test.api.promisepay.com/callbacks/f92d4ca1-4ee5-43f3-9e34-ca5f759c5e76" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"callbacks": "Successfully redacted"
}
Delete an existing Callback using a given :id.
Endpoint
DELETE /callbacks/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | callback id |
List Callback Responses
Example Request
curl -X "GET" "https://test.api.promisepay.com/callbacks/f92d4ca1-4ee5-43f3-9e34-ca5f759c5e76/responses" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"callback_responses": [
{
"id": "4476b384-fa48-4473-98ec-8fcdda4a1e84",
"created_at": "2016-04-18T00:35:36.879Z",
"url": "https://httpbin.org/post",
"payload": {
"message": "Assembly callback test"
},
"response": {
"error": "OK"
},
"response_code": 200
},
{
"id": "19d6edcc-f175-4e29-96ee-ec51145f92a7",
"created_at": "2016-04-18T00:35:37.263Z",
"url": "https://httpbin.org/post",
"payload": {
"message": "Assembly callback test"
},
"response": {
"error": "OK"
},
"response_code": 200
}
],
"meta": {
"limit": 10,
"offset": 0,
"total": 2
},
"links": {
"self": "/callbacks/f92d4ca1-4ee5-43f3-9e34-ca5f759c5e76/responses",
"callbacks": "/callbacks"
}
}
Retrieve an ordered and paginated list of the responses garnered from a callback using a given :id.
Endpoint
GET /callbacks/:id/responses
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | callback ID |
Show Callback Response
Example Request
curl -X "GET" "https://test.api.promisepay.com/callbacks/f92d4ca1-4ee5-43f3-9e34-ca5f759c5e76/responses/4476b384-fa48-4473-98ec-8fcdda4a1e84" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"callback_responses": {
"id": "4476b384-fa48-4473-98ec-8fcdda4a1e84",
"created_at": "2016-04-18T00:35:36.879Z",
"url": "https://httpbin.org/post",
"payload": {
"message": "Assembly callback test"
},
"response": {
"error": "OK"
},
"response_code": 200,
"links": {
"self": "/callbacks/f92d4ca1-4ee5-43f3-9e34-ca5f759c5e76/responses/4476b384-fa48-4473-98ec-8fcdda4a1e84",
"responses": "/callbacks/f92d4ca1-4ee5-43f3-9e34-ca5f759c5e76/responses"
}
}
}
Show details of a specific Callback response using a given :id.
Endpoint
GET /callbacks/:callback_id/responses/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| callback_id | string | callback ID |
| id | string | callback response ID |
Companies
If the User (seller or buyer) of an Item is a Company, then it is important to create an associated Company. The Company allows for invoices and other emails to be tailored with Company details rather than User details. A Company will also have an associated Address.
Create Company
Example Request
client.companies.create(
name: 'Samuel's Gardening',
legal_name: 'Samuel's Gardening Pty Ltd',
user_id: '',
tax_number: '100200300',
charge_tax: false,
address_line1: '500 Garden St',
address_line2: '',
city: 'Sydney',
state: 'NSW',
zip: '2000',
country: 'AUS',
phone: '+61491570156'
)
PromisePay::Company()->create(array(
"name" => "Samuel's Gardening",
"legal_name" => 'Samuel's Gardening Pty Ltd',
"user_id" => '',
"tax_number" => '100200300',
"charge_tax" => false,
"address_line1" => '500 Garden St',
"address_line2" => '',
"city" => 'Sydney',
"state" => "NSW",
"zip" => '2000',
"country" => 'AUS',
"phone" => '+61491570156',
));
curl -X "POST" "https://test.api.promisepay.com/companies" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"name\":\"Samuel's Gardening\",\"legal_name\":\"Samuel's Gardening Pty Ltd\",\"user_id\":\"\",\"tax_number\":\"100200300\",\"charge_tax\":false,\"address_line1\":\"500 Garden St\",\"address_line2\":\"\",\"city\":\"Sydney\",\"state\":\"NSW\",\"zip\":\"2000\",\"country\":\"AUS\",\"phone\":\"+61491570156\"}"
Example Response (201)
{
"companies": {
"legal_name": "Samuel's Gardening Pty Ltd",
"name": "Samuel's Gardening",
"tax_number": "100200300",
"charge_tax": false,
"id": "7b85aa9c-fc54-4449-afef-f52fc2b94cd3",
"related": {
"address": "cae0ada1-8e31-4bfc-aa24-5331f888cb12",
"users": "b278dbd0-48da-4824-8ab7-f82008682df2"
},
"links": {
"self": "/companies"
}
}
}
Create a Company associated with the User using a given user_id.
Note: Some parameters are required for KYC. See our guide on Onboarding a Seller for more information.
Endpoint
POST /companies
Parameters
| Parameter | Type | Description |
|---|---|---|
| name | String | company name |
| legal_name | String | company legal name |
| user_id required | String | user ID to associate with the company |
| tax_number | String | abn/tax number |
| charge_tax | String | Charge GST or not? |
| address_line1 | String | address line 1 |
| address_line2 | String | address line 2 |
| city | String | city |
| state | String | state |
| zip | String | zip |
| country required | String | 3 digit country code (eg. AUS) |
| phone | String | Company phone number |
List Companies
Example Request
client.companies.find_all
PromisePay::Company()->getList(array(
'limit' => 20,
'offset' => 0
));
curl -X "GET" "https://test.api.promisepay.com/companies" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"limit\":\"\",\"offset\":\"\"}"
Example Response (200)
{
"companies": [
{
"legal_name": null,
"name": null,
"id": "9280aa36-d7f8-4959-b1ed-0ace2c12cfa2",
"related": {
"address": "b7801205-6543-41a6-8b8f-f012f1061019"
},
"links": {
"self": "/companies/9280aa36-d7f8-4959-b1ed-0ace2c12cfa2"
}
},
{
"legal_name": "Samuel's Gardening Pty Ltd",
"name": "Samuel's Gardening",
"id": "7b85aa9c-fc54-4449-afef-f52fc2b94cd3",
"related": {
"address": "cae0ada1-8e31-4bfc-aa24-5331f888cb12",
"users": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/companies/7b85aa9c-fc54-4449-afef-f52fc2b94cd3"
}
}
],
"meta": {
"limit": 10,
"offset": 0,
"total": 2
},
"links": {
"self": "/companies"
}
}
Retrieve an ordered and paginated list of existing Companies.
Endpoint
GET /companies
Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | Integer | Number of records to retrieve. Up to 200. |
| offset | Integer | Number of records to offset. Required for pagination. |
Show Company
Example Request
client.companies.find('7b85aa9c-fc54-4449-afef-f52fc2b94cd3')
PromisePay::Company()->get('7b85aa9c-fc54-4449-afef-f52fc2b94cd3');
curl -X "GET" "https://test.api.promisepay.com/companies/7b85aa9c-fc54-4449-afef-f52fc2b94cd3" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"companies": {
"legal_name": "Samuel's Gardening Pty Ltd",
"name": "Samuel's Gardening",
"tax_number": "100200300",
"charge_tax": false,
"id": "7b85aa9c-fc54-4449-afef-f52fc2b94cd3",
"related": {
"address": "cae0ada1-8e31-4bfc-aa24-5331f888cb12",
"users": "b278dbd0-48da-4824-8ab7-f82008682df2"
},
"links": {
"self": "/companies/7b85aa9c-fc54-4449-afef-f52fc2b94cd3"
}
}
}
Show details of a specific Company using a given :id.
Endpoint
GET /companies/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | company ID |
Update Company
Example Request
client.companies.update(
id: "7b85aa9c-fc54-4449-afef-f52fc2b94cd3",
name: 'Samuel's Gardening',
legal_name: 'Samuel's Gardening Pty Ltd',
user_id: '',
tax_number: '100200300',
charge_tax: 'false',
address_line1: '500 Garden St',
address_line2: '',
city: 'Sydney',
state: 'NSW',
zip: '2000',
country: 'AUS',
phone: '+61491570156'
)
PromisePay::Company()->update('7b85aa9c-fc54-4449-afef-f52fc2b94cd3', array(
"name" => "Samuel's Gardening",
"legal_name" => 'Samuel's Gardening Pty Ltd',
"user_id" => '',
"tax_number" => '100200300',
"charge_tax" => 'false',
"address_line1" => '500 Garden St',
"address_line2" => '',
"city" => 'Sydney',
"state" => "NSW",
"zip" => '2000',
"country" => 'AUS',
"phone" => '+61491570156',
));
curl -X "PATCH" "https://test.api.promisepay.com/companies/7b85aa9c-fc54-4449-afef-f52fc2b94cd3" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"name\":\"Samuel's Gardening\",\"legal_name\":\"Samuel's Gardening Pty Ltd\",\"tax_number\":\"100200300\",\"charge_tax\":false,\"address_line1\":\"500 Garden St\",\"address_line2\":\"\",\"city\":\"Sydney\",\"state\":\"NSW\",\"zip\":\"2000\",\"country\":\"AUS\",\"phone\":\"+61491570156\"}"
Example Response (200)
{
"companies": {
"legal_name": "Samuel's Gardening Pty Ltd",
"name": "Samuel's Gardening",
"tax_number": "100200300",
"charge_tax": false,
"id": "7b85aa9c-fc54-4449-afef-f52fc2b94cd3",
"related": {
"address": "cae0ada1-8e31-4bfc-aa24-5331f888cb12",
"users": "b278dbd0-48da-4824-8ab7-f82008682df2"
},
"links": {
"self": "/companies/7b85aa9c-fc54-4449-afef-f52fc2b94cd3"
}
}
}
Update an existing Companies attributes using a given :id.
Endpoint
PATCH /companies
Parameters
| Parameter | Type | Description |
|---|---|---|
| id required | String | company id |
| name | String | company name |
| legal_name | String | company legal name |
| user_id | String | User id company is associated with |
| tax_number | String | abn/tax number |
| charge_tax | String | Charge GST or not? |
| address_line1 | String | address line 1 |
| address_line2 | String | address line 2 |
| city | String | city |
| state | String | state |
| zip | String | zip |
| country | String | 3 digit country code (eg. AUS) |
| phone | String | phone |
Direct Debit Authority
A Direct Debit Authority needs to be created in order for a Bank Account to be used as a funding source (Direct Debit/ACH).
The Direct Debit Authority is an authorization from the User to debit their Bank Account for the Item amount or for the funding of a Wallet Account. Ensure that you actually obtain this authorisation because in the event of an issue, it will be required as proof of authorization.
You will need to provide them with a link and checkbox to the Assembly direct debit agreement.
Create Direct Debit Authority
Example Request
client.direct_debit_authorities.create(
account_id: '9fda18e7-b1d3-4a83-830d-0cef0f62cd25',
amount: '10000'
)
curl -X "POST" "https://test.api.promisepay.com/direct_debit_authorities" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"account_id\":\"9fda18e7-b1d3-4a83-830d-0cef0f62cd25\",\"amount\":\"100000\"}"
Example Response (201)
{
"direct_debit_authorities": {
"id": "8f233e04-ffaa-4c9d-adf9-244853848e21",
"created_at": "2016-04-18T05:21:27.339Z",
"updated_at": "2016-04-18T05:21:27.339Z",
"amount": 100000,
"bank_bsb": "083001",
"debit_user_id": "481561",
"state": "approved",
"related": {
"bank_accounts": "9fda18e7-b1d3-4a83-830d-0cef0f62cd25"
},
"links": {
"self": "/direct_debit_authorities/8f233e04-ffaa-4c9d-adf9-244853848e21"
}
}
}
Create a Direct Debit Authority associated with a Bank Account.
The Direct Debit Authority is required to use a Bank Account as a funding source (Direct Debit/ACH).
Endpoint
POST /direct_debit_authorities
Parameters
| Parameter | Type | Description |
|---|---|---|
| account_id | String | bank account ID |
| amount | String | amount for direct debit in cents |
List Direct Debit Authorities
Example Request
client.charges.find_all("9fda18e7-b1d3-4a83-830d-0cef0f62cd25")
curl -X "GET" "https://test.api.promisepay.com/direct_debit_authorities" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"account_id\":\"9fda18e7-b1d3-4a83-830d-0cef0f62cd25\"}"
Example Response (200)
{
"direct_debit_authorities": [
{
"id": "8f233e04-ffaa-4c9d-adf9-244853848e21",
"created_at": "2016-04-18T05:21:27.339Z",
"updated_at": "2016-04-18T05:21:27.339Z",
"amount": 100000,
"bank_bsb": "083001",
"debit_user_id": "481561",
"state": "approved",
"links": {
"self": "/direct_debit_authorities/8f233e04-ffaa-4c9d-adf9-244853848e21"
}
}
],
"meta": {
"limit": 10,
"offset": 0,
"total": 1
},
"links": {
"self": "/direct_debit_authorities"
}
}
Retrieve an ordered and paginated list of existing Direct Debit Authorities.
Endpoint
GET /direct_debit_authorities
Parameters
| Parameter | Type | Description |
|---|---|---|
| account_id required | String | bank account ID |
| limit | Integer | Number of records to retrieve. Up to 200. |
| offset | Integer | Number of records to offset. Required for pagination. |
Show Direct Debit Authority
Example Request
client.direct_debit_authorities.find('8f233e04-ffaa-4c9d-adf9-244853848e21')
curl -X "GET" "https://test.api.promisepay.com/direct_debit_authorities/8f233e04-ffaa-4c9d-adf9-244853848e21" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"direct_debit_authorities": {
"id": "8f233e04-ffaa-4c9d-adf9-244853848e21",
"created_at": "2016-04-18T05:21:27.339Z",
"updated_at": "2016-04-18T05:21:27.339Z",
"amount": 100000,
"bank_bsb": "083001",
"debit_user_id": "481561",
"state": "approved",
"related": {
"bank_accounts": "9fda18e7-b1d3-4a83-830d-0cef0f62cd25"
},
"links": {
"self": "/direct_debit_authorities/8f233e04-ffaa-4c9d-adf9-244853848e21"
}
}
}
Show details of a specific Direct Debit Authority using a given :id.
Endpoint
GET /direct_debit_authorities/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | direct debit authority ID |
Delete Direct Debit Authority
Example Request
client.direct_debit_authorities.delete('8f233e04-ffaa-4c9d-adf9-244853848e21')
curl -X "DELETE" "https://test.api.promisepay.com/direct_debit_authorities/8f233e04-ffaa-4c9d-adf9-244853848e21" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
null
Delete a specific Direct Debit Authority using a given :id.
Endpoint
DELETE /direct_debit_authorities/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | direct debit authority ID |
Fees
As a platform or marketplace you will want to charge your users Fees. Fees are applied to Items and will add or subtract from the amount based on the User, payment type or Disbursement account type.
Fees are disbursed when the funds are released from Escrow, or when the Express transaction completes. Fees are refunded when doing a full refund. Proportional fees, are disbursed for partial releases and also partial refunds.
Create Fee
Example Request
client.fees.create(
name: 'Seller Success Fee',
fee_type_id: '2',
amount: '200',
cap: '',
min: '',
max: ''.
to: 'seller',
)
PromisePay::Fee()->create(array(
"name" => 'Seller Success Fee',
"fee_type_id" => '2',
"amount" => '200',
"cap" => '',
"min" => '',
"max" => '',
"to" => 'seller'
));
var repo = container.Resolve<IFeeRepository>();
repo.CreateFee(new Dictionary<string, object>{
{"name", "Seller Success Fee"},
{"fee_type_id", "2"},
{"amount", "200"},
{"cap", ""},
{"min", ""},
{"max", ""},
{"to", "seller"}
});
curl -X "POST" "https://test.api.promisepay.com/fees" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"name\":\"Seller Success Fee\",\"fee_type_id\":\"2\",\"amount\":\"200\",\"cap\":\"\",\"min\":\"\",\"max\":\"\",\"to\":\"seller\"}"
Example Response (201)
{
"fees": {
"id": "36020976-f345-4d0f-b860-9c025ccce668",
"created_at": "2016-04-18T05:51:16.518Z",
"updated_at": "2016-04-18T05:51:16.518Z",
"name": "Seller Success Fee",
"fee_type_id": 2,
"amount": 200,
"cap": null,
"min": null,
"max": null,
"to": "seller",
"links": {
"self": "/fees/36020976-f345-4d0f-b860-9c025ccce668"
}
}
}
Create a Fee to be associated with an Item. Fees will add or subtract from the Item amount based on the User, payment type or Disbursement account type.
Fees can be Fixed or Percentage based.
Fees can be capped, have a maximum amount and/or a minimum amount.
Endpoint
POST /fees
Parameters
| Parameter | Type | Description |
|---|---|---|
| name | String | Name |
| fee_type_id | String | 1 = Fixed, 2 = Percentage, 3 = Percentage with Cap, 4 = Percentage with Min |
| amount | String | Amount in cents |
| cap | String | Cap the Fee |
| min | String | Minimum Fee |
| max | String | Maximum Fee |
| to | String | Who pays the fee (buyer, seller, cc, int_wire) |
List Fees
Example Request
client.fees.find_all
PromisePay::Fee()->getList(array(
'limit' => 20,
'offset' => 0
));
var repo = container.Resolve<IFeeRepository>();
repo.ListFees();
curl -X "GET" "https://test.api.promisepay.com/fees" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"fees": [
{
"id": "36020976-f345-4d0f-b860-9c025ccce668",
"created_at": "2016-04-18T05:51:16.518Z",
"updated_at": "2016-04-18T05:51:16.518Z",
"name": "Seller Success Fee",
"fee_type_id": 2,
"amount": 200,
"cap": null,
"min": null,
"max": null,
"to": "seller",
"links": {
"self": "/fees/36020976-f345-4d0f-b860-9c025ccce668"
}
}
],
"meta": {
"limit": 10,
"offset": 0,
"total": 1
},
"links": {
"self": "/fees"
}
}
Retrieve an ordered and paginated list of existing Fees.
Endpoint
GET /fees
Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | Integer | Number of records to retrieve. Up to 200. |
| offset | Integer | Number of records to offset. Required for pagination. |
Show Fee
Example Request
client.fees.find('36020976-f345-4d0f-b860-9c025ccce668')
PromisePay::Fee()->get('36020976-f345-4d0f-b860-9c025ccce668');
var repo = container.Resolve<IFeeRepository>();
repo.GetFeeById("36020976-f345-4d0f-b860-9c025ccce668");
curl -X "GET" "https://test.api.promisepay.com/fees/36020976-f345-4d0f-b860-9c025ccce668" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
-H "Content-Type: application/json" \
-d "{\"item_amount\":\"20000\"}"
Example Response (200)
{
"fees": {
"id": "36020976-f345-4d0f-b860-9c025ccce668",
"created_at": "2016-04-18T05:51:16.518Z",
"updated_at": "2016-04-18T05:51:16.518Z",
"name": "Seller Success Fee",
"fee_type_id": 2,
"amount": 200,
"cap": null,
"min": null,
"max": null,
"to": "seller",
"calculated_fee": 400,
"links": {
"self": "/fees/36020976-f345-4d0f-b860-9c025ccce668?item_amount=20000"
}
}
}
Show details of a specific Fee using a given :id. If the item_amount is specified, the response also shows the calculated_fee based on a percentage of the item_amount.
Endpoint
GET /fees/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | fee ID |
| item_amount | Integer | the cost of the item in cents on which the calculated fee is based |
Items
Items are the core component of your payments workflow. They connect Users, allowing them to pay and receive money for an item or service. Fees can also be set up, allowing you to collect money for various scenarios. These can be set up for buyers & sellers, payment types and Disbursement destinations. Different types of Items can be created: Express, Escrow, Escrow Partial Release or Approve.
Before creating an Item, ensure the Users (buyer & seller) and Fees are created, you will need to pass their :ids as parameters.
Create Item
Example Request
client.items.create(
id: '100fd4a0-0538-11e6-b512-3e1d05defe78',
name: 'Landscaping Job #001',
amount: 20000,
payment_type: 2,
buyer_id: '064d6800-fff3-11e5-86aa-5e5517507c66',
seller_id: '5830def0-ffe8-11e5-86aa-5e5517507c66',
fee_ids: '36020976-f345-4d0f-b860-9c025ccce668',
description: 'Planting of natives, removal of tree stump.',
due_date: '22/04/2016'
)
PromisePay::Item()->create(array(
"id" => '100fd4a0-0538-11e6-b512-3e1d05defe78',
"name" => 'Landscaping Job #001',
"amount" => 2000,
"payment_type_id" => 2,
"buyer_id" => '064d6800-fff3-11e5-86aa-5e5517507c66',
"seller_id" => '5830def0-ffe8-11e5-86aa-5e5517507c66',
"fee_ids" => '36020976-f345-4d0f-b860-9c025ccce668',
"description" => 'Planting of natives, removal of tree stump.',
"due_date" => '22/04/2016'
));
var repo = container.Resolve<IItemRepository>();
repo.CreateItem(new Dictionary<string, object>{
{"id", "100fd4a0-0538-11e6-b512-3e1d05defe78"},
{"name", "Landscaping Job #001"},
{"amount", 2000},
{"payment_type", 2},
{"buyer_id", "064d6800-fff3-11e5-86aa-5e5517507c66"},
{"seller_id", "5830def0-ffe8-11e5-86aa-5e5517507c66"},
{"fee_ids", "36020976-f345-4d0f-b860-9c025ccce668"},
{"description", "Planting of natives, removal of tree stump."},
{"due_date", "22/04/2016"}
});
curl -X "POST" "https://test.api.promisepay.com/items" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"id\":\"100fd4a0-0538-11e6-b512-3e1d05defe78\",\"name\":\"Landscaping Job #001\",\"amount\":\"20000\",\"payment_type\":\"2\",\"buyer_id\":\"064d6800-fff3-11e5-86aa-5e5517507c66\",\"seller_id\":\"5830def0-ffe8-11e5-86aa-5e5517507c66\",\"fee_ids\":\"36020976-f345-4d0f-b860-9c025ccce668\",\"description\":\"Planting of natives, removal of tree stump.\",\"due_date\":\"22/04/2016\"}"
Example Response (201)
{
"items": {
"id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"name": "Landscaping Job #001",
"description": "Planting of natives, removal of tree stump.",
"custom_descriptor": null,
"created_at": "2016-04-18T07:37:29.580Z",
"updated_at": "2016-04-18T07:37:29.580Z",
"state": "pending",
"net_amount": 20000,
"chargedback_amount": 0,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 400,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22000,
"amount": 20000,
"payment_type_id": 2,
"due_date": "2016-04-22",
"pending_release_amount": 0,
"dynamic_descriptor": null,
"deposit_reference": "100014013961629",
"promisepay_fee": 350,
"total_outstanding": 20000,
"total_amount": 20000,
"currency": "AUD",
"payment_method": "pending",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items",
"buyers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/buyers",
"sellers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/sellers",
"status": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/status",
"fees": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/fees",
"transactions": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/transactions",
"batch_transactions": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/batch_transactions",
"wire_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/wire_details",
"bpay_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/bpay_details"
}
}
}
Create an Item. Items require two Users, a buyer and a seller.
The payment type can be one of Escrow, Express, Escrow Partial Release or Approve.
The buyer_id and seller_id are your unique user identifiers.
Endpoint
POST /items
Parameters
| Parameter | Type | Description |
|---|---|---|
| id required | String | Unique ID that can be generated by the platform. Cannot contain ’.’ character. Contact Assembly support if you want item IDs to be generated automatically. |
| name | String | A name for the item |
| amount | String | The cost in cents |
| currency | String | Currency code. ISO 4217 alpha-3 currency code. This is an optional field and if not provided, the item will be created with the default currency of the marketplace |
| payment_type | Integer | 1 = Escrow, 2 = Express, 3 = Escrow Partial Release, 4 = Approve |
| buyer_id required | String | Marketplace buyer ID |
| seller_id required | String | Marketplace /Seller ID |
| fee_ids | String | A comma separated list of fee IDs to apply |
| description | String | A description of the item |
| buyer_url | String | Link for the buyer CTA |
| seller_url | String | Link for the seller CTA |
| tax_invoice | Boolean | Toggle to generate tax invoice once Item is complete |
| due_date | String | When the Item payment is due. dd/mm/yyyy |
| custom_descriptor | String | When custom_descriptors are enabled, this is the information to appear on credit card and direct debit statements. |
List Items
Example Request
client.items.find_all
PromisePay::Item()->getList(array(
'limit' => 20,
'offset' => 0
));
var repo = container.Resolve<IItemRepository>();
repo.ListItems();
curl -X "GET" "https://test.api.promisepay.com/items" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json"
Example Response (200)
{
"items": [
{
"id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"name": "Landscaping Job #001",
"description": "Planting of natives, removal of tree stump.",
"created_at": "2016-04-18T07:37:29.580Z",
"updated_at": "2016-04-18T07:37:29.580Z",
"state": "pending",
"payment_type_id": 2,
"status": 22000,
"amount": 20000,
"deposit_reference": "100014013961629",
"buyer_name": "Bella Buyer",
"buyer_country": "AUS",
"buyer_email": "bella.buyer@assemblypayments.com",
"seller_name": "Samuel Seller",
"seller_country": "AUS",
"seller_email": "samuel.seller@assemblypayments.com",
"currency": "AUD",
"links": {
"self": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78",
"buyers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/buyers",
"sellers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/sellers",
"status": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/status",
"fees": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/fees",
"transactions": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/transactions",
"batch_transactions": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/batch_transactions",
"wire_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/wire_details",
"bpay_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/bpay_details"
}
}
],
"links": {
"self": "/items"
},
"meta": {
"limit": 10,
"offset": 0,
"total": 1
}
}
Retrieve an ordered and paginated list of existing Items.
Endpoint
GET /items
Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | Integer | Number of records to retrieve. Up to 200. |
| offset | Integer | Number of records to offset. Required for pagination. |
| search | String | search string |
Show Item
Example Request
item = client.items.find('100fd4a0-0538-11e6-b512-3e1d05defe78')
PromisePay::Item()->get('100fd4a0-0538-11e6-b512-3e1d05defe78');
var repo = container.Resolve<IItemRepository>();
repo.GetItemById("100fd4a0-0538-11e6-b512-3e1d05defe78");
curl -X "GET" "https://test.api.promisepay.com/items/100fd4a0-0538-11e6-b512-3e1d05defe78" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"items": {
"id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"name": "Landscaping Job #001",
"description": "Planting of natives, removal of tree stump.",
"custom_descriptor": null,
"created_at": "2016-04-18T07:37:29.580Z",
"updated_at": "2016-04-18T07:37:29.580Z",
"state": "pending",
"net_amount": 20000,
"chargedback_amount": 0,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 400,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22000,
"amount": 20000,
"payment_type_id": 2,
"due_date": "2016-04-22",
"pending_release_amount": 0,
"dynamic_descriptor": null,
"deposit_reference": "100014013961629",
"promisepay_fee": 350,
"total_outstanding": 20000,
"total_amount": 20000,
"currency": "AUD",
"payment_method": "pending",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78",
"buyers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/buyers",
"sellers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/sellers",
"status": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/status",
"fees": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/fees",
"transactions": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/transactions",
"batch_transactions": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/batch_transactions,"
"wire_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/wire_details",
"bpay_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/bpay_details"
}
}
}
Show details of a specific Item using a given :id.
Endpoint
GET /items/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Update Item
Example Request
client.items.update(
id: '100fd4a0-0538-11e6-b512-3e1d05defe78',
name: 'Landscaping Job #001',
amount: 25000,
custom_descriptor: 'SSeller Job001',
)
PromisePay::Item()->update('100fd4a0-0538-11e6-b512-3e1d05defe78', array(
"id" => '100fd4a0-0538-11e6-b512-3e1d05defe78',
"amount" => 25000,
"custom_descriptor" => 'SSeller Job001',
));
var repo = container.Resolve<IItemRepository>();
repo.UpdateItemById(new Dictionary<string,object){
{"id", "100fd4a0-0538-11e6-b512-3e1d05defe78"},
{"amount", 25000},
{"custom_descriptor", "SSeller Job001"},
});
curl -X "PATCH" "https://test.api.promisepay.com/items/100fd4a0-0538-11e6-b512-3e1d05defe78" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"amount\":\"25000\", \"custom_descriptor\":\"SSeller Job001\"}"
Example Response (200)
{
"items": {
"id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"name": "Landscaping Job #001",
"description": "Planting of natives, removal of tree stump.",
"custom_descriptor": "SSeller Job001",
"created_at": "2016-04-18T07:37:29.580Z",
"updated_at": "2016-04-18T07:40:16.852Z",
"state": "pending",
"net_amount": 25000,
"chargedback_amount": 0,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 500,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22000,
"amount": 25000,
"payment_type_id": 2,
"due_date": "2016-04-22",
"pending_release_amount": 0,
"dynamic_descriptor": null,
"deposit_reference": "100014013961629",
"promisepay_fee": 437,
"total_outstanding": 25000,
"total_amount": 25000,
"currency": "AUD",
"payment_method": "pending",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78",
"buyers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/buyers",
"sellers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/sellers",
"status": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/status",
"fees": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/fees",
"transactions": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/transactions",
"batch_transactions": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/batch_transactions",
"wire_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/wire_details",
"bpay_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/bpay_details"
}
}
}
Update an existing Items attributes using a given :id.
Note: An item can only be updated if it’s in pending state. Once an item has begun a payment process, you cannot update it.
Endpoint
PATCH /items/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| name | String | A name for the item |
| amount | String | The cost in cents |
| description | String | A description of the item |
| buyer_id | String | Marketplace buyer ID |
| seller_id | String | Marketplace /Seller ID |
| custom_descriptor | String | When custom_descriptors are enabled, this is the information to appear on credit card and direct debit statements. |
Delete Item
Example Request
item.delete(
id: '100fd4a0-0538-11e6-b512-3e1d05defe78')
PromisePay::Item()->delete('100fd4a0-0538-11e6-b512-3e1d05defe78');
var repo = container.Resolve<IItemRepository>();
repo.DeleteItembyId("100fd4a0-0538-11e6-b512-3e1d05defe78");
curl -X "DELETE" "https://test.api.promisepay.com/items/100fd4a0-0538-11e6-b512-3e1d05defe78" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response
{
"items": {
"id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"name": "Landscaping Job #001",
"description": "Planting of natives, removal of tree stump.",
"custom_descriptor": "SSeller Job001",
"created_at": "2016-04-18T07:37:29.580Z",
"updated_at": "2016-04-18T07:41:01.997Z",
"state": "cancelled",
"net_amount": 25000,
"chargedback_amount": 0,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 500,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22575,
"amount": 25000,
"payment_type_id": 2,
"due_date": "2016-04-22",
"pending_release_amount": 0,
"dynamic_descriptor": null,
"deposit_reference": "100014013961629",
"promisepay_fee": 437,
"total_outstanding": 25000,
"total_amount": 25000,
"currency": "AUD",
"payment_method": "pending",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78",
"buyers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/buyers",
"sellers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/sellers",
"status": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/status",
"fees": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/fees",
"transactions": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/transactions",
"batch_transactions": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/batch_transactions",
"wire_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/wire_details",
"bpay_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/bpay_details"
}
}
}
Delete an existing Item using a given :id.
Endpoint
DELETE /items/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Show Item Status
Example Request
item.status.find('100fd4a0-0538-11e6-b512-3e1d05defe78')
PromisePay::Item()->getStatus('100fd4a0-0538-11e6-b512-3e1d05defe78');
var repo = container.Resolve<IItemRepository>();
repo.GetStatusForItembyId("100fd4a0-0538-11e6-b512-3e1d05defe78");
curl -X "GET" "https://test.api.promisepay.com/items/100fd4a0-0538-11e6-b512-3e1d05defe78/status" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"items": {
"id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"status": 22000,
"state": "pending"
}
}
Show the status of an Item using a given :id.
Endpoint
GET /items/:id/status
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Show Item Buyer
Example Request
item.buyer.find('100fd4a0-0538-11e6-b512-3e1d05defe78')
PromisePay::Item()->getBuyer('100fd4a0-0538-11e6-b512-3e1d05defe78');
var repo = container.Resolve<IItemRepository>();
repo.GetBuyerForItemById("100fd4a0-0538-11e6-b512-3e1d05defe78");
curl -X "GET" "https://test.api.promisepay.com/items/100fd4a0-0538-11e6-b512-3e1d05defe78/buyers" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"users": {
"created_at": "2016-04-12T08:10:47.458Z",
"updated_at": "2016-04-12T08:10:47.458Z",
"full_name": "Bella Buyer",
"email": "bella.buyer@assemblypayments.com",
"mobile": "+61491570159",
"phone": null,
"logo_url": null,
"color_1": null,
"color_2": null,
"first_name": "Bella",
"last_name": "Buyer",
"id": "064d6800-fff3-11e5-86aa-5e5517507c66",
"custom_descriptor": null,
"location": "AUS",
"verification_state": "approved",
"held_state": false,
"roles": [
"customer"
],
"dob": "encrypted",
"government_number": "encrypted",
"drivers_license": null,
"flags": {},
"related": {
"addresses": "d2b7dcea-0a4e-4ce4-9259-982619d90ad4"
},
"links": {
"self": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/buyers",
"items": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/items",
"card_accounts": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/card_accounts",
"paypal_accounts": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/paypal_accounts",
"bank_accounts": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/bank_accounts",
"wallet_accounts": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/wallet_accounts"
}
}
}
Show the buyer User associated with the Item using a given :id.
Endpoint
GET /items/:id/buyers
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Show Item Seller
Example Request
item.seller.find('100fd4a0-0538-11e6-b512-3e1d05defe78')
PromisePay::Item()->getSeller('100fd4a0-0538-11e6-b512-3e1d05defe78');
var repo = container.Resolve<IItemRepository>();
repo.GetSellerForItemById("100fd4a0-0538-11e6-b512-3e1d05defe78");
curl -X "GET" "https://test.api.promisepay.com/items/100fd4a0-0538-11e6-b512-3e1d05defe78/sellers" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"users": {
"created_at": "2016-04-12T08:13:10.665Z",
"updated_at": "2016-04-12T09:07:55.083Z",
"full_name": "Samuel Seller",
"email": "samuel.seller@assemblypayments.com",
"mobile": "+61491570156",
"phone": null,
"logo_url": null,
"color_1": null,
"color_2": null,
"first_name": "Samuel",
"last_name": "Seller",
"id": "5830def0-ffe8-11e5-86aa-5e5517507c66",
"custom_descriptor": "Sam Garden Jobs",
"location": "AUS",
"verification_state": "approved",
"held_state": false,
"roles": [
"customer"
],
"dob": "encrypted",
"government_number": "encrypted",
"drivers_license": null,
"flags": {},
"related": {
"addresses": "fe602dcf-4175-4f88-b5be-3beb04092dcd",
"companies": "7b85aa9c-fc54-4449-afef-f52fc2b94cd3",
"payout_account": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc"
},
"links": {
"self": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/sellers",
"items": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/items",
"card_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/card_accounts",
"paypal_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/paypal_accounts",
"bank_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/bank_accounts",
"wallet_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/wallet_accounts"
}
}
}
Show the seller User associated with the Item using a given :id.
Endpoint
GET /items/:id/sellers
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Show Item Fees
Example Request
item.fees.find('100fd4a0-0538-11e6-b512-3e1d05defe78')
PromisePay::Item()->getListOfFees('100fd4a0-0538-11e6-b512-3e1d05defe78');
var repo = container.Resolve<IItemRepository>();
repo.ListFeesForItemById("100fd4a0-0538-11e6-b512-3e1d05defe78");
curl -X "GET" "https://test.api.promisepay.com/items/100fd4a0-0538-11e6-b512-3e1d05defe78/fees" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"fees": [
{
"id": "7b04522c-7a8f-462d-98fe-9c033673525d",
"created_at": "2016-04-18T07:37:30.085Z",
"updated_at": "2016-04-18T07:37:30.085Z",
"fee_list": {
"id": "36020976-f345-4d0f-b860-9c025ccce668",
"name": "Seller Success Fee",
"fee_type": 2,
"amount": 200,
"cap": null,
"min": null,
"max": null,
"to": "seller"
},
"links": {
"self": "/fees/7b04522c-7a8f-462d-98fe-9c033673525d"
}
}
],
"meta": {
"limit": 10,
"offset": 0,
"total": 0
},
"links": {
"self": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/fees"
}
}
Show the Fees associated with the Item using a given :id.
Endpoint
GET /items/:id/fees
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Show Item Wire Details
Example Request
item.wire_details.find('100fd4a0-0538-11e6-b512-3e1d05defe78')
PromisePay::Item()->getWireDetails('100fd4a0-0538-11e6-b512-3e1d05defe78');
var repo = container.Resolve<IItemRepository>();
repo.GetWireDetailsForItemById("100fd4a0-0538-11e6-b512-3e1d05defe78");
curl -X "GET" "https://test.api.promisepay.com/items/100fd4a0-0538-11e6-b512-3e1d05defe78/wire_details" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"items": {
"id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"wire_details": {
"beneficiary": "Assembly Payments",
"address_line1": "500 Bourke Street",
"city": "Melbourne",
"state": "VIC",
"zip": "3000",
"routing_number": "083001",
"account_number": "844144573",
"bank_name": "National Australia Bank",
"swift": "NATAAU3303M",
"reference": "100014013961629",
"amount": "$250.00",
"currency": "AUD",
"country": "Australia"
}
}
}
Show the Item wire payment details using a given :id.
Endpoint
GET /items/:id/wire_details
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Show Item BPay Details
Example Request
item.bpay_details.find('100fd4a0-0538-11e6-b512-3e1d05defe78')
PromisePay::Item()->getBPayDetails('100fd4a0-0538-11e6-b512-3e1d05defe78');
var repo = container.Resolve<IItemRepository>();
repo.GetBPayDetailsForItemById("100fd4a0-0538-11e6-b512-3e1d05defe78");
curl -X "GET" "https://test.api.promisepay.com/items/100fd4a0-0538-11e6-b512-3e1d05defe78/bpay_details" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"items": {
"id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"bpay_details": {
"biller_code": "230680",
"reference": "100014013961629",
"amount": "$250.00",
"currency": "AUD"
}
}
}
Show the Item BPay payment details using a given :id.
Endpoint
GET /items/:id/bpay_details
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
List Item Transactions
Example Request
item.transactions
PromisePay::Item()->getListOfTransactions('100fd4a0-0538-11e6-b512-3e1d05defe78');
var repo = container.Resolve<IItemRepository>();
repo.ListTransactionsForItemById("100fd4a0-0538-11e6-b512-3e1d05defe78");
curl -X "GET" "https://test.api.promisepay.com/items/100fd4a0-0538-11e6-b512-3e1d05defe78/transactions" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"transactions": [
{
"id": "6b68f5dc-b8a8-44cf-a7e8-80f350178152",
"created_at": "2016-04-18T08:14:58.238Z",
"updated_at": "2016-04-18T08:14:58.238Z",
"description": "Credit of $250.00 to Item by Debit of $250.00 from Credit Card",
"type": "payment",
"type_method": "credit_card",
"state": "successful",
"user_id": "064d6800-fff3-11e5-86aa-5e5517507c66",
"user_name": "Bella Buyer",
"account_id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"account_type": "item",
"item_name": "Landscaping Job #001",
"dynamic_descriptor": null,
"amount": 25000,
"currency": "AUD",
"debit_credit": "credit",
"related": {
"transactions": [
{
"id": "7a138862-f821-412d-a91e-367ed7391fe7",
"account_id": "930a7f78-6bf6-4f33-8cfc-b82c787b5f83",
"account_type": "card_account",
"user_id": "064d6800-fff3-11e5-86aa-5e5517507c66",
"user_name": "Bella Buyer"
}
]
}
},
{
"id": "ca02a5c6-2235-4b97-ac5d-8c7d2c93d65a",
"created_at": "2016-04-18T08:15:02.639Z",
"updated_at": "2016-04-18T08:15:02.688Z",
"description": "Debit of $5.00 from Item for Credit of $5.00 to Wallet Account",
"type": "fee",
"type_method": "wallet_account_transfer",
"state": "successful",
"user_id": "5830def0-ffe8-11e5-86aa-5e5517507c66",
"user_name": "Samuel Seller",
"account_id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"account_type": "item",
"item_name": "Landscaping Job #001",
"dynamic_descriptor": null,
"amount": 500,
"currency": "AUD",
"debit_credit": "debit",
"related": {
"transactions": [
{
"id": "29feec2d-749b-44f6-a822-e7253482c7ba",
"account_id": "4f4a9428-5fdd-4b4a-a7e3-0919cbba5e20",
"account_type": "wallet_account",
"user_id": "5830def0-ffe8-11e5-86aa-5e5517507c66",
"user_name": "Samuel Seller"
}
],
"fee": "7b04522c-7a8f-462d-98fe-9c033673525d"
}
},
{
"id": "121d5b31-e634-4d56-ba63-a6b9afcf949b",
"created_at": "2016-04-20T21:00:33.185Z",
"updated_at": "2016-05-31T12:13:21.642Z",
"description": "Debit of $245.00 from Item for Credit of $245.00 to Wallet Account",
"type": "release",
"type_method": "wallet_account_transfer",
"state": "successful",
"user_id": "064d6800-fff3-11e5-86aa-5e5517507c66",
"user_name": "Bella Buyer",
"account_id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"account_type": "item",
"item_name": "Landscaping Job #001",
"dynamic_descriptor": null,
"amount": 24500,
"currency": "AUD",
"debit_credit": "debit",
"related": {
"transactions": [
{
"id": "7192bc8c-6b67-4e15-aabd-a1a15c402d3d",
"account_id": "385b50bb-237a-42cb-9382-22953e191ae6",
"account_type": "wallet_account",
"user_id": "064d6800-fff3-11e5-86aa-5e5517507c66",
"user_name": "Bella Buyer"
}
]
}
}
],
"meta": {
"limit": 10,
"offset": 0,
"total": 3
},
"links": {
"self": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/transactions"
}
}
Retrieve an ordered and paginated list of Transactions associated with the Item using a given :id.
Endpoint
GET /items/:id/transactions
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
List Item Batch Transactions
Example Request
item.batch_transactions
curl -X "GET" "https://test.api.promisepay.com/items/100fd4a0-0538-11e6-b512-3e1d05defe78/batch_transactions" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"batch_transactions": [
{
"id": "ad688d54-6791-4f1d-add7-88fbd89b70d1",
"created_at": "2016-04-26T08:56:25.035Z",
"updated_at": "2016-04-26T21:00:38.435Z",
"status": 12200,
"type": "disbursement",
"type_method": "direct_credit",
"batch_id": 316,
"reference": null,
"state": "batched",
"user_id": "5830def0-ffe8-11e5-86aa-5e5517507c66",
"account_id": "385b50bb-237a-42cb-9382-22953e191ae6",
"from_user_name": "Samuel Seller",
"from_user_id": "5830def0-ffe8-11e5-86aa-5e5517507c66",
"account_type": "wallet_account",
"amount": 10000,
"currency": "AUD",
"debit_credit": "credit",
"description": "Credit of $100.00 to Wallet Account by Debit of $100.00 from Bank Account",
"related": {
"account_to": {
"id": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
"account_type": "bank_account",
"user_id": "5830def0-ffe8-11e5-86aa-5e5517507c66"
}
}
}
],
"meta": {
"limit": 10,
"offset": 0,
"total": 1
},
"links": {
"self": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/batch_transactions"
}
}
Retrieve an ordered and paginated list of BatchTransactions associated with the Item using a given :id. This will include both direct debits coming in, and the disbursements going out.
Endpoint
GET /items/:id/transactions
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Item Actions
Once you have created an Item you can perform actions on it. The actions that can be performed are limited by the Items payment type and the Items current state.
The most common escrow workflow is to request_payment, make_payment, request_release and release_payment. There are also refund actions and dispute actions.
The most common express workflow is to request_payment and make_payment. An express item releases the funds immediately to the seller.
Some Item actions require parameters to be passed with the action. For example, make_payment requires the :id of the payment account. More detail is found for the Item action in the relevant reference guide page.
Request Payment
Example Request
item.request_payment(id: '100fd4a0-0538-11e6-b512-3e1d05defe78')
PromisePay::Item()->requestPayment('100fd4a0-0538-11e6-b512-3e1d05defe78');
var repo = container.Resolve<IItemRepository>();
repo.RequestPayment("100fd4a0-0538-11e6-b512-3e1d05defe78");
curl -X "PATCH" "https://test.api.promisepay.com/items/100fd4a0-0538-11e6-b512-3e1d05defe78/request_payment" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"items": {
"id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"name": "Landscaping Job #001",
"description": "Planting of natives, removal of tree stump.",
"created_at": "2016-04-18T07:37:29.580Z",
"updated_at": "2016-04-18T08:05:24.510Z",
"state": "payment_required",
"net_amount": 25000,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 500,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22100,
"amount": 25000,
"payment_type_id": 2,
"due_date": "2016-04-22",
"pending_release_amount": 0,
"deposit_reference": "100014013961629",
"promisepay_fee": 437,
"total_outstanding": 25000,
"total_amount": 25000,
"currency": "AUD",
"payment_method": "pending",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/request_payment",
"buyers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/buyers",
"sellers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/sellers",
"status": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/status",
"fees": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/fees",
"transactions": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/transactions",
"wire_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/wire_details",
"bpay_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/bpay_details"
}
}
}
Request payment for an Item. This can trigger an email or an SMS with instructions for payment. Contact support@assemblypayments.com if you require email or SMS notifications configured. This will transition the Item state to payment_required.
Endpoint
PATCH /items/:id/request_payment
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Make Payment
Example Request - Express
item.make_payment(
id: '100fd4a0-0538-11e6-b512-3e1d05defe78',
account_id: '930a7f78-6bf6-4f33-8cfc-b82c787b5f83',
device_id: 'sample device ID',
ip_address: '192.0.0.1'
)
PromisePay::Item()->makePayment('100fd4a0-0538-11e6-b512-3e1d05defe78', array(
'account_id' => '930a7f78-6bf6-4f33-8cfc-b82c787b5f83',
'device_id' => 'sample device ID',
'ip_address' => '192.0.0.1'
));
var repo = container.Resolve<IItemRepository>();
repo.MakePayment("100fd4a0-0538-11e6-b512-3e1d05defe78", "930a7f78-6bf6-4f33-8cfc-b82c787b5f83");
curl -X "PATCH" "https://test.api.promisepay.com/items/100fd4a0-0538-11e6-b512-3e1d05defe78/make_payment" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"account_id\":\"930a7f78-6bf6-4f33-8cfc-b82c787b5f83\",\"device_id\":\"sample device ID\",\"ip_address\":\"192.0.0.1\"}"
Example Request - Escrow
item.make_payment(
id: 'e57120ea-053d-11e6-b512-3e1d05defe78',
account_id: '930a7f78-6bf6-4f33-8cfc-b82c787b5f83',
device_id: 'sample device ID',
ip_address: '192.0.0.1'
)
PromisePay::Item()->makePayment('e57120ea-053d-11e6-b512-3e1d05defe78', array(
'account_id' => '930a7f78-6bf6-4f33-8cfc-b82c787b5f83',
'device_id' => 'sample device ID',
'ip_address' => '192.0.0.1'
));
var repo = container.Resolve<IItemRepository>();
repo.MakePayment("e57120ea-053d-11e6-b512-3e1d05defe78", "930a7f78-6bf6-4f33-8cfc-b82c787b5f83");
curl -X "PATCH" "https://test.api.promisepay.com/items/e57120ea-053d-11e6-b512-3e1d05defe78/make_payment" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"account_id\":\"930a7f78-6bf6-4f33-8cfc-b82c787b5f83\",\"device_id\":\"sample device ID\",\"ip_address\":\"192.0.0.1\"}"
Example Response - Express (200)
{
"items": {
"id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"name": "Landscaping Job #001",
"description": "Planting of natives, removal of tree stump.",
"created_at": "2016-04-18T07:37:29.580Z",
"updated_at": "2016-04-18T08:15:02.822Z",
"state": "completed",
"net_amount": 25000,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 500,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22500,
"amount": 25000,
"payment_type_id": 2,
"due_date": "2016-04-22",
"pending_release_amount": 24500,
"deposit_reference": "100014013961629",
"promisepay_fee": 905,
"total_outstanding": 0,
"total_amount": 25000,
"currency": "AUD",
"payment_method": "credit card",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/make_payment",
"buyers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/buyers",
"sellers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/sellers",
"status": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/status",
"fees": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/fees",
"transactions": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/transactions",
"wire_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/wire_details",
"bpay_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/bpay_details"
}
}
}
Example Response - Escrow (200)
{
"items": {
"id": "e57120ea-053d-11e6-b512-3e1d05defe78",
"name": "Landscaping Job #002",
"description": "Removal of weeds.",
"created_at": "2016-04-18T08:17:32.708Z",
"updated_at": "2016-04-18T08:18:00.940Z",
"state": "payment_deposited",
"net_amount": 10000,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 200,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22200,
"amount": 10000,
"payment_type_id": 1,
"due_date": "2016-04-28",
"pending_release_amount": 0,
"deposit_reference": "100014013962667",
"promisepay_fee": 380,
"total_outstanding": 10000,
"total_amount": 10000,
"currency": "AUD",
"payment_method": "credit card",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@asemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/make_payment",
"buyers": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/buyers",
"sellers": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/sellers",
"status": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/status",
"fees": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/fees",
"transactions": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/transactions",
"wire_details": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/wire_details",
"bpay_details": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/bpay_details"
}
}
}
Make a payment for an Item. Pass the :account_id of a Bank Account or a Card Account associated with the Item’s buyer.
The Item state will transition to one of payment_held, payment_pending, payment_deposited for an Escrow or Escrow Partial Release payment type.
The Item state will transition to one of payment_held, payment_pending or completed for an Express or Approve payment type.
Endpoint
PATCH /items/:id/make_payment
Parameters
| Parameter | Type | Description |
|---|---|---|
| id required | String | Marketplace item ID |
| account_id required | String | Account id of the bank account/credit card, etc making payment (not user id) |
| ip_address required | String | IP Information provided by Assembly client-side SDKs |
| device_id required | String | Device information provided by Assembly client-side SDKs |
Request Release
Example Request
item.request_release(
id: 'e57120ea-053d-11e6-b512-3e1d05defe78')
PromisePay::Item()->requestRelease('e57120ea-053d-11e6-b512-3e1d05defe78');
var repo = container.Resolve<IItemRepository>();
repo.RequestRelease("e57120ea-053d-11e6-b512-3e1d05defe78");
curl -X "PATCH" "https://test.api.promisepay.com/items/e57120ea-053d-11e6-b512-3e1d05defe78/request_release" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"items": {
"id": "e57120ea-053d-11e6-b512-3e1d05defe78",
"name": "Landscaping Job #002",
"description": "Removal of weeds.",
"created_at": "2016-04-18T08:17:32.708Z",
"updated_at": "2016-04-18T08:19:47.198Z",
"state": "work_completed",
"net_amount": 10000,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 200,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22300,
"amount": 10000,
"payment_type_id": 1,
"due_date": "2016-04-28",
"pending_release_amount": 0,
"deposit_reference": "100014013962667",
"promisepay_fee": 380,
"total_outstanding": 10000,
"total_amount": 10000,
"currency": "AUD",
"payment_method": "credit card",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/request_release",
"buyers": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/buyers",
"sellers": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/sellers",
"status": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/status",
"fees": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/fees",
"transactions": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/transactions",
"wire_details": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/wire_details",
"bpay_details": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/bpay_details"
}
}
}
Request release of funds held in escrow, from an Item with an Escrow or Escrow Partial Release payment type. This will transition the Item state to work_completed.
Endpoint
PATCH /items/:id/request_release
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
| release_amount | String | For partial releases, in cents |
Release Payment
Example Request
item.release_payment(
id: 'e57120ea-053d-11e6-b512-3e1d05defe78' )
PromisePay::Item()->releasePayment('e57120ea-053d-11e6-b512-3e1d05defe78');
var repo = container.Resolve<IItemRepository>();
repo.ReleasePayment("e57120ea-053d-11e6-b512-3e1d05defe78");
curl -X "PATCH" "https://test.api.promisepay.com/items/e57120ea-053d-11e6-b512-3e1d05defe78/release_payment" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"items": {
"id": "e57120ea-053d-11e6-b512-3e1d05defe78",
"name": "Landscaping Job #002",
"description": "Removal of weeds.",
"created_at": "2016-04-18T08:17:32.708Z",
"updated_at": "2016-04-18T08:20:20.374Z",
"state": "completed",
"net_amount": 10000,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 200,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22500,
"amount": 10000,
"payment_type_id": 1,
"due_date": "2016-04-28",
"pending_release_amount": 9800,
"deposit_reference": "100014013962667",
"promisepay_fee": 380,
"total_outstanding": 0,
"total_amount": 10000,
"currency": "AUD",
"payment_method": "credit card",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/release_payment",
"buyers": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/buyers",
"sellers": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/sellers",
"status": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/status",
"fees": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/fees",
"transactions": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/transactions",
"wire_details": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/wire_details",
"bpay_details": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/bpay_details"
}
}
}
Release funds held in escrow from an Item with an Escrow or Escrow Partial Release payment type. This will transition the Item state to completed.
Endpoint
PATCH /items/:id/release_payment
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
| release_amount | String | For partial releases, in cents |
| flag_release | Boolean | If release flagging enabled for your marketplace |
Request Refund
Example Request
item.request_refund(
id: '4c423a39-358a-4ea9-a19e-9727a9738fdb',
refund_amount: 10000,
refund_message: 'Frame already constructed.'
)
PromisePay::Item()->requestRefund('4c423a39-358a-4ea9-a19e-9727a9738fdb', array(
'refund_amount' => 10000,
'refund_message' => 'Frame already constructed.'
));
var repo = container.Resolve<IItemRepository>();
repo.RequestRefund("4c423a39-358a-4ea9-a19e-9727a9738fdb", "10000", "Frame already constructed.");
curl -X "PATCH" "https://test.api.promisepay.com/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/request_refund" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"refund_amount\":\"10000\",\"refund_message\":\"Frame already constructed.\"}"
Example Response (200)
{
"items": {
"id": "4c423a39-358a-4ea9-a19e-9727a9738fdb",
"name": "Landscaping Job #003",
"description": "Building of deck.",
"created_at": "2016-04-18T08:21:34.258Z",
"updated_at": "2016-04-18T08:22:48.609Z",
"state": "refund_flagged",
"net_amount": 30000,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 600,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22650,
"amount": 30000,
"payment_type_id": 1,
"due_date": "2016-04-28",
"pending_release_amount": 0,
"deposit_reference": "100014013962813",
"promisepay_fee": 1080,
"total_outstanding": 30000,
"total_amount": 30000,
"currency": "AUD",
"payment_method": "credit card",
"refund_message": "Frame already constructed.",
"refund_amount": 10000,
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/request_refund",
"buyers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/buyers",
"sellers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/sellers",
"status": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/status",
"fees": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/fees",
"transactions": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/transactions",
"wire_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/wire_details",
"bpay_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/bpay_details"
}
}
}
Request a refund for an Item. This will transition the Item status to refund_flagged.
Endpoint
PATCH /items/:id/request_refund
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
| refund_amount | String | For partial refunds, if they are enabled for marketplace |
| refund_message | String | Reason for the request |
Refund
Example Request
item.refund(
id: '4c423a39-358a-4ea9-a19e-9727a9738fdb'
refund_amount: '10000',
refund_message: 'Stable deck refund.'
)
PromisePay::Item()->refund('4c423a39-358a-4ea9-a19e-9727a9738fdb', array(
'refund_amount' => 10000,
'refund_message' => 'Stable deck refund.'
));
var repo = container.Resolve<IItemRepository>();
repo.Refund("4c423a39-358a-4ea9-a19e-9727a9738fdb", "10000", "Stable deck refund.");
curl -X "PATCH" "https://test.api.promisepay.com/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/refund" \
-H "Cookie: request_method=PATCH" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"refund_amount\":\"10000\",\"refund_message\":\"Stable deck refund.\"}"
Example Response (200)
{
"items": {
"id": "4c423a39-358a-4ea9-a19e-9727a9738fdb",
"name": "Landscaping Job #003",
"description": "Building of deck.",
"created_at": "2016-04-18T08:21:34.258Z",
"updated_at": "2016-04-18T09:01:43.998Z",
"state": "payment_deposited",
"net_amount": 20000,
"refunded_amount": 10000,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 400,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22200,
"amount": 30000,
"payment_type_id": 1,
"due_date": "2016-04-28",
"pending_release_amount": 0,
"deposit_reference": "100014013962813",
"promisepay_fee": 730,
"total_outstanding": 20000,
"total_amount": 30000,
"currency": "AUD",
"payment_method": "credit card",
"refund_message": "Stable deck refund.",
"refund_amount": 10000,
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/refund",
"buyers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/buyers",
"sellers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/sellers",
"status": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/status",
"fees": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/fees",
"transactions": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/transactions",
"wire_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/wire_details",
"bpay_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/bpay_details"
}
}
}
Refund an Item’s funds held in escrow. An partial amount can be specified otherwise the full amount will be refunded. This will transition the Item state to ‘refunded’ if the full amount is refunded, or to the previously held state if a partial amount is specified.
Endpoint
PATCH /items/:id/refund
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
| refund_amount | String | For partial refunds, if they are enabled for marketplace |
| refund_message | String | Reason for the request |
Decline Refund
Example Request
item.decline_refund
curl -X "PATCH" "https://test.api.promisepay.com/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/decline_refund" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"items": {
"id": "4c423a39-358a-4ea9-a19e-9727a9738fdb",
"name": "Landscaping Job #003",
"description": "Building of deck.",
"created_at": "2016-04-18T08:21:34.258Z",
"updated_at": "2016-04-18T08:25:51.024Z",
"state": "payment_deposited",
"net_amount": 30000,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 600,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22200,
"amount": 30000,
"payment_type_id": 1,
"due_date": "2016-04-28",
"pending_release_amount": 0,
"deposit_reference": "100014013962813",
"promisepay_fee": 1080,
"total_outstanding": 30000,
"total_amount": 30000,
"currency": "AUD",
"payment_method": "credit card",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/decline_refund",
"buyers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/buyers",
"sellers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/sellers",
"status": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/status",
"fees": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/fees",
"transactions": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/transactions",
"wire_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/wire_details",
"bpay_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/bpay_details"
}
}
}
Decline a refund request for an Item. This will transition the Item state to the previously held state.
Endpoint
PATCH /items/:id/decline_refund
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Raise Dispute
Example Request
item.raise_dispute(user_id: '064d6800-fff3-11e5-86aa-5e5517507c66')
curl -X "PATCH" "https://test.api.promisepay.com/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/raise_dispute" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"user_id\":\"064d6800-fff3-11e5-86aa-5e5517507c66\"}"
Example Response (200)
{
"items": {
"id": "4c423a39-358a-4ea9-a19e-9727a9738fdb",
"name": "Landscaping Job #003",
"description": "Building of deck.",
"created_at": "2016-04-18T08:21:34.258Z",
"updated_at": "2016-04-18T08:30:04.289Z",
"state": "problem_flagged",
"net_amount": 30000,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 600,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22400,
"amount": 30000,
"payment_type_id": 1,
"due_date": "2016-04-28",
"pending_release_amount": 0,
"deposit_reference": "100014013962813",
"promisepay_fee": 1080,
"total_outstanding": 30000,
"total_amount": 30000,
"currency": "AUD",
"payment_method": "credit card",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/raise_dispute",
"buyers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/buyers",
"sellers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/sellers",
"status": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/status",
"fees": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/fees",
"transactions": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/transactions",
"wire_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/wire_details",
"bpay_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/bpay_details"
}
}
}
Raise a dispute for the Item. This will transition the Item state to problem_flagged.
Endpoint
PATCH /items/:id/raise_dispute
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
| user_id | String | External id of user raising dispute |
Request Dispute Resolution
Example Request
item.request_resolve_dispute
curl -X "PATCH" "https://test.api.promisepay.com/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/request_resolve_dispute" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"user_id\":\"5830def0-ffe8-11e5-86aa-5e5517507c66\",\"dispute_message\":\"Deck fixed.\"}"
Example Response (200)
{
"items": {
"id": "4c423a39-358a-4ea9-a19e-9727a9738fdb",
"name": "Landscaping Job #003",
"description": "Building of deck.",
"created_at": "2016-04-18T08:21:34.258Z",
"updated_at": "2016-04-18T08:35:09.020Z",
"state": "problem_resolve_requested",
"net_amount": 30000,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 600,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22410,
"amount": 30000,
"payment_type_id": 1,
"due_date": "2016-04-28",
"pending_release_amount": 0,
"deposit_reference": "100014013962813",
"promisepay_fee": 1080,
"total_outstanding": 30000,
"total_amount": 30000,
"currency": "AUD",
"payment_method": "credit card",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/request_resolve_dispute",
"buyers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/buyers",
"sellers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/sellers",
"status": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/status",
"fees": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/fees",
"transactions": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/transactions",
"wire_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/wire_details",
"bpay_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/bpay_details"
}
}
}
Request that the dispute be resolved. This will transition the Item state to problem_resolve_requested.
Endpoint
PATCH /items/:id/request_resolve_dispute
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Resolve Dispute
Example Request
item.resolve_dispute
curl -X "PATCH" "https://test.api.promisepay.com/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/resolve_dispute" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"user_id\":\"064d6800-fff3-11e5-86aa-5e5517507c66\",\"dispute_message\":\"Deck stable.\"}"
Example Response (200)
{
"items": {
"id": "4c423a39-358a-4ea9-a19e-9727a9738fdb",
"name": "Landscaping Job #003",
"description": "Building of deck.",
"created_at": "2016-04-18T08:21:34.258Z",
"updated_at": "2016-04-18T08:33:55.653Z",
"state": "payment_deposited",
"net_amount": 30000,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 600,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22200,
"amount": 30000,
"payment_type_id": 1,
"due_date": "2016-04-28",
"pending_release_amount": 0,
"deposit_reference": "100014013962813",
"promisepay_fee": 1080,
"total_outstanding": 30000,
"total_amount": 30000,
"currency": "AUD",
"payment_method": "credit card",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/resolve_dispute",
"buyers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/buyers",
"sellers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/sellers",
"status": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/status",
"fees": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/fees",
"transactions": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/transactions",
"wire_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/wire_details",
"bpay_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/bpay_details"
}
}
}
Resolve a dispute. This will transition the Item state to the previously held state.
Endpoint
PATCH /items/:id/resolve_dispute
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Escalate Dispute
Example Request
item.escalate_dispute
curl -X "PATCH" "https://test.api.promisepay.com/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/escalate_dispute" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"user_id\":\"5830def0-ffe8-11e5-86aa-5e5517507c66\",\"dispute_message\":\"Deck still not fixed.\"}"
Example Response (200)
{
"items": {
"id": "4c423a39-358a-4ea9-a19e-9727a9738fdb",
"name": "Landscaping Job #003",
"description": "Building of deck.",
"created_at": "2016-04-18T08:21:34.258Z",
"updated_at": "2016-04-18T08:36:15.947Z",
"state": "problem_escalated",
"net_amount": 30000,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 600,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22420,
"amount": 30000,
"payment_type_id": 1,
"due_date": "2016-04-28",
"pending_release_amount": 0,
"deposit_reference": "100014013962813",
"promisepay_fee": 1080,
"total_outstanding": 30000,
"total_amount": 30000,
"currency": "AUD",
"payment_method": "credit card",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/escalate_dispute",
"buyers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/buyers",
"sellers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/sellers",
"status": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/status",
"fees": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/fees",
"transactions": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/transactions",
"wire_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/wire_details",
"bpay_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/bpay_details"
}
}
}
Escalate a dispute raised against an Item. This will transition the Item state to problem_escalated.
Endpoint
PATCH /items/:id/escalate_dispute
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Acknowledge Wire Transfer
Example Request
item.acknowledge_wire(
id: '100fd4a0-0538-11e6-b512-3e1d05defe78')
PromisePay::Item()->acknowledgeWire('100fd4a0-0538-11e6-b512-3e1d05defe78');
var repo = container.Resolve<IItemRepository>();
repo.AcknowledgeWire("100fd4a0-0538-11e6-b512-3e1d05defe78");
curl -X "PATCH" "https://test.api.promisepay.com/items/100fd4a0-0538-11e6-b512-3e1d05defe78/acknowledge_wire" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"items": {
"id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"name": "Landscaping Job #001",
"description": "Planting of natives, removal of tree stump.",
"created_at": "2016-04-18T07:37:29.580Z",
"updated_at": "2016-04-18T08:06:19.638Z",
"state": "wire_pending",
"net_amount": 25000,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 500,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22110,
"amount": 25000,
"payment_type_id": 2,
"due_date": "2016-04-22",
"pending_release_amount": 0,
"deposit_reference": "100014013961629",
"promisepay_fee": 437,
"total_outstanding": 25000,
"total_amount": 25000,
"currency": "AUD",
"payment_method": "pending",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/acknowledge_wire",
"buyers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/buyers",
"sellers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/sellers",
"status": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/status",
"fees": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/fees",
"transactions": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/transactions",
"wire_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/wire_details",
"bpay_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/bpay_details"
}
}
}
Acknowledge that funds are being wired for payment. This will transition the Item state to wire_pending.
Endpoint
PATCH /items/:id/acknowledge_wire
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Revert Wire Transfer
Example Request
item.revert_wire(
id: '100fd4a0-0538-11e6-b512-3e1d05defe78' )
PromisePay::Item()->revertWire('100fd4a0-0538-11e6-b512-3e1d05defe78');
var repo = container.Resolve<IItemRepository>();
repo.RevertWire("100fd4a0-0538-11e6-b512-3e1d05defe78");
curl -X "PATCH" "https://test.api.promisepay.com/items/100fd4a0-0538-11e6-b512-3e1d05defe78/revert_wire" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"items": {
"id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"name": "Landscaping Job #001",
"description": "Planting of natives, removal of tree stump.",
"created_at": "2016-04-18T07:37:29.580Z",
"updated_at": "2016-04-18T08:06:55.176Z",
"state": "pending",
"net_amount": 25000,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 500,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22000,
"amount": 25000,
"payment_type_id": 2,
"due_date": "2016-04-22",
"pending_release_amount": 0,
"deposit_reference": "100014013961629",
"promisepay_fee": 437,
"total_outstanding": 25000,
"total_amount": 25000,
"currency": "AUD",
"payment_method": "pending",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/revert_wire",
"buyers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/buyers",
"sellers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/sellers",
"status": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/status",
"fees": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/fees",
"transactions": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/transactions",
"wire_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/wire_details",
"bpay_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/bpay_details"
}
}
}
Revert an acknowledge wire Item Action. This will transition the Item state to pending.
Endpoint
PATCH /items/:id/revert_wire
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Cancel
Example Request
item.cancel(
id: '100fd4a0-0538-11e6-b512-3e1d05defe78')
PromisePay::Item()->cancelItem('100fd4a0-0538-11e6-b512-3e1d05defe78');
var repo = container.Resolve<IItemRepository>();
repo.Cancel("100fd4a0-0538-11e6-b512-3e1d05defe78");
curl -X "PATCH" "https://test.api.promisepay.com/items/100fd4a0-0538-11e6-b512-3e1d05defe78/cancel" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"items": {
"id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"name": "Landscaping Job #001",
"description": "Planting of natives, removal of tree stump.",
"created_at": "2016-04-18T07:37:29.580Z",
"updated_at": "2016-04-18T08:08:08.434Z",
"state": "cancelled",
"net_amount": 25000,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 500,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22575,
"amount": 25000,
"payment_type_id": 2,
"due_date": "2016-04-22",
"pending_release_amount": 0,
"deposit_reference": "100014013961629",
"promisepay_fee": 437,
"total_outstanding": 25000,
"total_amount": 25000,
"currency": "AUD",
"payment_method": "pending",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/cancel",
"buyers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/buyers",
"sellers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/sellers",
"status": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/status",
"fees": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/fees",
"transactions": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/transactions",
"wire_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/wire_details",
"bpay_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/bpay_details"
}
}
}
Cancel an Item. This will transition the Item state to cancelled. Items can only be cancelled if they haven’t been actioned in any other way.
Endpoint
PATCH /items/:id/cancel
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Send Tax Invoice
Example Request
item.send_tax_invoice
curl -X "PATCH" "https://test.api.promisepay.com/items/e57120ea-053d-11e6-b512-3e1d05defe78/send_tax_invoice" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"items": {
"id": "e57120ea-053d-11e6-b512-3e1d05defe78",
"name": "Landscaping Job #002",
"description": "Removal of weeds.",
"created_at": "2016-04-18T08:17:32.708Z",
"updated_at": "2016-04-18T08:20:20.374Z",
"state": "completed",
"net_amount": 10000,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 200,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22500,
"amount": 10000,
"payment_type_id": 1,
"due_date": "2016-04-28",
"pending_release_amount": 9800,
"deposit_reference": "100014013962667",
"promisepay_fee": 380,
"total_outstanding": 0,
"total_amount": 10000,
"currency": "AUD",
"payment_method": "credit card",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/send_tax_invoice",
"buyers": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/buyers",
"sellers": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/sellers",
"status": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/status",
"fees": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/fees",
"transactions": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/transactions",
"wire_details": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/wire_details",
"bpay_details": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/bpay_details"
}
}
}
Email a Tax Invoice to the Users associated with the Item.
Endpoint
PATCH /items/:id/send_tax_invoice
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Request Tax Invoice
Example Request
item.request_tax_invoice
curl -X "PATCH" "https://test.api.promisepay.com/items/e57120ea-053d-11e6-b512-3e1d05defe78/send_tax_invoice" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"items": {
"id": "e57120ea-053d-11e6-b512-3e1d05defe78",
"name": "Landscaping Job #002",
"description": "Removal of weeds.",
"created_at": "2016-04-18T08:17:32.708Z",
"updated_at": "2016-04-18T08:20:20.374Z",
"state": "completed",
"net_amount": 10000,
"refunded_amount": 0,
"released_amount": 0,
"buyer_fees": 0,
"seller_fees": 200,
"credit_card_fee": 0,
"paypal_fee": 0,
"seller_url": "",
"buyer_url": "",
"direct_debit_fee": 0,
"status": 22500,
"amount": 10000,
"payment_type_id": 1,
"due_date": "2016-04-28",
"pending_release_amount": 9800,
"deposit_reference": "100014013962667",
"promisepay_fee": 380,
"total_outstanding": 0,
"total_amount": 10000,
"currency": "AUD",
"payment_method": "credit card",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c66"
},
"links": {
"self": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/send_tax_invoice",
"buyers": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/buyers",
"sellers": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/sellers",
"status": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/status",
"fees": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/fees",
"transactions": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/transactions",
"wire_details": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/wire_details",
"bpay_details": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/bpay_details"
}
}
}
Request a Tax Invoice be sent to the Users associated with an Item.
Endpoint
PATCH /items/:id/request_tax_invoice
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Authorize Payment
Example Request
curl -X "PATCH" "https://test.api.promisepay.com/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/authorize_payment" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"account_id\":\"930a7f78-6bf6-4f33-8cfc-b82c787b5f83\"}"
Example Response (200)
{
"items": {
"id": "4c423a39-358a-4ea9-a19e-9727a9738fdb",
"name": "Landscaping Job #003",
"description": "Building of deck.",
"custom_descriptor": null,
"created_at": "2017-02-15T05:31:12.692Z",
"updated_at": "2017-02-15T05:51:34.675Z",
"state": "payment_authorized",
"net_amount": 30000,
"chargedback_amount": 0,
"refunded_amount": 0,
"released_amount": 0,
"seller_url": "",
"buyer_url": "",
"remaining_amount": 0,
"status": 22180,
"amount": 30000,
"payment_type_id": 1,
"due_date": null,
"requested_release_amount": 0,
"pending_release_amount": 0,
"dynamic_descriptor": null,
"deposit_reference": "100014013961629",
"buyer_fees": 0,
"seller_fees": 400,
"credit_card_fee": 0,
"direct_debit_fee": 0,
"paypal_fee": 0,
"promisepay_fee": 1080,
"total_outstanding": 30000,
"total_amount": 30000,
"currency": "AUD",
"payment_method": "pending",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c6"
},
"links": {
"self": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/authorize_payment?account_id=930a7f78-6bf6-4f33-8cfc-b82c787b5f83",
"buyers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/buyers",
"sellers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/sellers",
"status": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/status",
"fees": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/fees",
"transactions": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/transactions",
"batch_transactions": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/batch_transactions",
"wire_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/wire_details",
"bpay_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/bpay_details",
"tds_checks": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/tds_checks"
}
}
}
Where pre-authentication is enabled on a platform, initiates a credit card payment authorization for an item.
When an authorization is successful, your platform holds the item amount for capture, but there is no transfer of funds happening.
This call is used with the Capture Payment or Void Payment calls.
Endpoint
PATCH /items/:id/authorize_payment
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
| account_id | String | Card account ID |
Capture Payment
Example Request
curl -X "PATCH" "https://test.api.promisepay.com/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/capture_payment" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
Example Response (200)
{
"items": {
"id": "4c423a39-358a-4ea9-a19e-9727a9738fdb",
"name": "Landscaping Job #003",
"description": "Building of deck.",
"custom_descriptor": null,
"created_at": "2017-02-15T05:31:12.692Z",
"updated_at": "2017-02-15T05:51:34.675Z",
"state": "payment_deposited",
"net_amount": 30000,
"chargedback_amount": 0,
"refunded_amount": 0,
"released_amount": 0,
"seller_url": "",
"buyer_url": "",
"remaining_amount": 0,
"status": 22200,
"amount": 30000,
"payment_type_id": 1,
"due_date": null,
"requested_release_amount": 0,
"pending_release_amount": 0,
"dynamic_descriptor": null,
"deposit_reference": "100014013961629",
"buyer_fees": 0,
"seller_fees": 400,
"credit_card_fee": 0,
"direct_debit_fee": 0,
"paypal_fee": 0,
"promisepay_fee": 1080,
"total_outstanding": 0,
"total_amount": 30000,
"currency": "AUD",
"payment_method": "credit card",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c6"
},
"links": {
"self": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/capture_payment",
"buyers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/buyers",
"sellers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/sellers",
"status": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/status",
"fees": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/fees",
"transactions": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/transactions",
"batch_transactions": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/batch_transactions",
"wire_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/wire_details",
"bpay_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/bpay_details",
"tds_checks": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/tds_checks"
}
}
}
Where pre-authentication is enabled on a platform, completes a credit card payment for an item whose payment is authorized.
This call is used with the Authorize Payment call.
Endpoint
PATCH /items/:id/capture_payment
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Void Payment
Example Request
curl -X "PATCH" "https://test.api.promisepay.com/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/void_payment" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
Example Response (200)
{
"items": {
"id": "4c423a39-358a-4ea9-a19e-9727a9738fdb",
"name": "Landscaping Job #003",
"description": "Building of deck.",
"custom_descriptor": null,
"created_at": "2017-02-15T05:31:12.692Z",
"updated_at": "2017-02-15T05:51:34.675Z",
"state": "voided",
"net_amount": 30000,
"chargedback_amount": 0,
"refunded_amount": 0,
"released_amount": 0,
"seller_url": "",
"buyer_url": "",
"remaining_amount": 0,
"status": 22195,
"amount": 30000,
"payment_type_id": 1,
"due_date": null,
"requested_release_amount": 0,
"pending_release_amount": 0,
"dynamic_descriptor": null,
"deposit_reference": "100014013961629",
"buyer_fees": 0,
"seller_fees": 400,
"credit_card_fee": 0,
"direct_debit_fee": 0,
"paypal_fee": 0,
"promisepay_fee": 1080,
"total_outstanding": 30000,
"total_amount": 30000,
"currency": "AUD",
"payment_method": "pending",
"buyer_name": "Bella Buyer",
"buyer_email": "bella.buyer@assemblypayments.com",
"buyer_country": "AUS",
"seller_name": "Samuel Seller",
"seller_email": "samuel.seller@assemblypayments.com",
"seller_country": "AUS",
"payment_credit_card_enabled": true,
"payment_direct_debit_enabled": true,
"related": {
"buyers": "064d6800-fff3-11e5-86aa-5e5517507c66",
"sellers": "5830def0-ffe8-11e5-86aa-5e5517507c6"
},
"links": {
"self": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/void_payment",
"buyers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/buyers",
"sellers": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/sellers",
"status": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/status",
"fees": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/fees",
"transactions": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/transactions",
"batch_transactions": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/batch_transactions",
"wire_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/wire_details",
"bpay_details": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/bpay_details",
"tds_checks": "/items/4c423a39-358a-4ea9-a19e-9727a9738fdb/tds_checks"
}
}
}
Where pre-authentication is enabled on a platform, voids the payment_authorized status for an item.
This call is used with the Authorize Payment call.
Note: Not all payment gateways support the Void Payment API call. In this case, you can wait until a payment authorization expires. A payment authorisation expires after 3 to 6 days if not captured.
Endpoint
PATCH /items/:id/void_payment
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Marketplace item ID |
Marketplaces
Marketplaces represent your platform, it is an object that is related to the principal and primary owners of the platform.
Show Marketplace
Example Request
client.marketplace
curl -X "GET" "https://test.api.promisepay.com/marketplace" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"marketplaces": {
"id": "c298d7ea-ea8c-486e-95d9-1e45ae3787ab",
"name": "Walkthrough",
"short_name": null,
"color_1": null,
"color_2": null,
"color_3": null,
"color_4": null,
"color_5": null,
"website": null,
"payment_frequency": null,
"alt_marketplace_id": null,
"state": "fully_approved",
"logo": null,
"active": true,
"alt_marketplace_auth": null,
"business_information": {
"principal_name": null,
"principal_government_number": null,
"incorporation_date": null,
"bank_account_holder": null,
"bank_account_number": null,
"bank_routing_number": null,
"avg_transaction_value": null,
"monthly_transactions": null,
"monthly_disputes": null,
"monthly_refunds": null,
"monthly_chargebacks": null,
"unique_users": null,
"company_phone": null,
"company_country": null,
"transaction_time": null,
"payments_flow": null,
"business_model_description": null,
"customer_support_email": null,
"bank_name": null,
"bank_account_type": null,
"bank_holder_type": null
},
"marketplace_addons": [
{
"name": "Fraud protection",
"enabled": true
},
{
"name": "End user support",
"enabled": true
}
],
"currency": "AUD",
"email": "walkthrough@assemblypayments.com",
"seller_white_labeled": false,
"partial_refunds": true,
"related": {
"users": "ec2700f6834b3f57b6531553fdf290f7",
"company": "9280aa36-d7f8-4959-b1ed-0ace2c12cfa2"
},
"links": {
"self": "/marketplace",
"principal": "/users/ec2700f6834b3f57b6531553fdf290f7",
"company": "/company/9280aa36-d7f8-4959-b1ed-0ace2c12cfa2"
}
}
}
Show details of your Platform, providing access to your configuration and related User and Company.
Endpoint
GET /marketplace
Token Auth
Generate Token
Example Request
client.generate_token(
token_type: 'card',
user_id: '064d6800-fff3-11e5-86aa-5e5517507c66'
)
var repo = container.Resolve<ITokenRepository>();
repo.GenerateCardToken(new Dictionary<string, object>{
{"token_type", "card"},
{"user_id", "064d6800-fff3-11e5-86aa-5e5517507c66"}
});
curl -X "POST" "https://test.api.promisepay.com/token_auths" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"token_type\":\"card\",\"user_id\":\"064d6800-fff3-11e5-86aa-5e5517507c66\"}"
Example Response (200)
{
"token_auth": {
"token_type": "card",
"token": "6e37598a3b33582b1dfcf13d5e2e45e3",
"user_id": "064d6800-fff3-11e5-86aa-5e5517507c66"
}
}
Create a token, either for a bank or a card account, that can be used with the PromisePay.js package to securely send Assembly credit card details.
Endpoint
POST /token_auths
Parameters
| Parameter | Type | Description |
|---|---|---|
| token_type | String | token type ID; use bank or card |
| user_id | String | Buyer or Seller ID (already created) |
Transactions
Transactions relate to Items. There are typically multiple Transactions per Item. An example: The inital funding, the release of funds, and Fees.
Note: Disbursement transactions are shown using the Batch Transactions API calls.
List Transactions
Example Request
client.transactions.find_all
PromisePay::Transaction()->getList(array(
'limit' => 20,
'offset' => 0
));
var repo = container.Resolve<ITransactionRepository>();
repo.ListTransactions();
curl -X "GET" "https://test.api.promisepay.com/transactions" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"limit\":\"2\"}"
Example Response (200)
{
"transactions": [
{
"id": "7a138862-f821-412d-a91e-367ed7391fe7",
"created_at": "2016-04-18T08:14:58.221Z",
"updated_at": "2016-04-18T08:14:58.258Z",
"description": "Debit of $250.00 from Credit Card for Credit of $250.00 to Item",
"type": "payment",
"type_method": "credit_card",
"state": "successful",
"user_id": "064d6800-fff3-11e5-86aa-5e5517507c66",
"account_id": "930a7f78-6bf6-4f33-8cfc-b82c787b5f83",
"account_type": "card_account",
"amount": 25000,
"currency": "AUD",
"debit_credit": "debit",
"related": {
"transactions": [
{
"id": "6b68f5dc-b8a8-44cf-a7e8-80f350178152",
"account_id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"account_type": "item",
"user_id": "064d6800-fff3-11e5-86aa-5e5517507c66"
}
]
}
},
{
"id": "6b68f5dc-b8a8-44cf-a7e8-80f350178152",
"created_at": "2016-04-18T08:14:58.238Z",
"updated_at": "2016-04-18T08:14:58.238Z",
"description": "Credit of $250.00 to Item by Debit of $250.00 from Credit Card",
"type": "payment",
"type_method": "credit_card",
"state": "successful",
"user_id": "064d6800-fff3-11e5-86aa-5e5517507c66",
"account_id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"account_type": "item",
"amount": 25000,
"currency": "AUD",
"debit_credit": "credit",
"related": {
"transactions": [
{
"id": "7a138862-f821-412d-a91e-367ed7391fe7",
"account_id": "930a7f78-6bf6-4f33-8cfc-b82c787b5f83",
"account_type": "card_account",
"user_id": "064d6800-fff3-11e5-86aa-5e5517507c66"
}
]
}
}
],
"meta": {
"limit": 2,
"offset": 0,
"total": 16
},
"links": {
"self": "/transactions"
}
}
Retrieve an ordered and paginated list of Transactions.
Endpoint
GET /transactions
Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | Integer | Number of records to retrieve. Up to 200. |
| offset | Integer | Number of records to offset. Required for pagination. |
| account_id | Integer | Bank, Card, PayPal or Wallet Account ID. |
| item_id | Integer | Item ID. |
| transaction_type | String | The type of transaction. Options: payment, refund, disbursement, fee, deposit, withdrawal. |
| transaction_type_method | The method the transaction was carried out with. Options: credit_card, wire_transfer, wallet_account_transfer. | |
| direction | String | Direction of the transaction. Options: debit, credit. |
Show Transaction
Example Request
client.transactions.find('7a138862-f821-412d-a91e-367ed7391fe7')
PromisePay::Transaction()->get('7a138862-f821-412d-a91e-367ed7391fe7');
var repo = container.Resolve<ITransactionRepository>();
repo.GetTransactionById("7a138862-f821-412d-a91e-367ed7391fe7");
curl -X "GET" "https://test.api.promisepay.com/transactions/7a138862-f821-412d-a91e-367ed7391fe7" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"transactions": {
"id": "7a138862-f821-412d-a91e-367ed7391fe7",
"created_at": "2016-04-18T08:14:58.221Z",
"updated_at": "2016-04-18T08:14:58.258Z",
"description": "Debit of $250.00 from Credit Card for Credit of $250.00 to Item",
"type": "payment",
"type_method": "credit_card",
"state": "successful",
"user_id": "064d6800-fff3-11e5-86aa-5e5517507c66",
"account_id": "930a7f78-6bf6-4f33-8cfc-b82c787b5f83",
"account_type": "card_account",
"amount": 25000,
"currency": "AUD",
"debit_credit": "debit",
"related": {
"transactions": [
{
"id": "6b68f5dc-b8a8-44cf-a7e8-80f350178152",
"account_id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"account_type": "item",
"user_id": "064d6800-fff3-11e5-86aa-5e5517507c66"
}
]
},
"links": {
"self": "/transactions/7a138862-f821-412d-a91e-367ed7391fe7",
"users": "/transactions/7a138862-f821-412d-a91e-367ed7391fe7/users",
"fees": "/transactions/7a138862-f821-412d-a91e-367ed7391fe7/fees",
"wallet_accounts": "/transactions/7a138862-f821-412d-a91e-367ed7391fe7/wallet_accounts",
"card_accounts": "/transactions/7a138862-f821-412d-a91e-367ed7391fe7/card_accounts",
"paypal_accounts": "/transactions/7a138862-f821-412d-a91e-367ed7391fe7/paypal_accounts",
"bank_accounts": "/transactions/7a138862-f821-412d-a91e-367ed7391fe7/bank_accounts",
"items": "/transactions/7a138862-f821-412d-a91e-367ed7391fe7/items"
}
}
}
Show details of a specific Transaction using a given :id.
Endpoint
GET /transactions/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Transaction ID |
Show Transaction User
Example Request
transaction.users.find('7a138862-f821-412d-a91e-367ed7391fe7')
PromisePay::Transaction()->getUser('7a138862-f821-412d-a91e-367ed7391fe7');
var repo = container.Resolve<ITransactionRepository>();
repo.GetUserForTransactionById("7a138862-f821-412d-a91e-367ed7391fe7");
curl -X "GET" "https://test.api.promisepay.com/transactions/7a138862-f821-412d-a91e-367ed7391fe7/users" \
-H "Cookie: request_method=PATCH" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"users": {
"created_at": "2016-04-12T08:10:47.458Z",
"updated_at": "2016-04-12T08:10:47.458Z",
"full_name": "Bella Buyer",
"email": "bella.buyer@example.com",
"mobile": "+61491570159",
"phone": null,
"logo_url": null,
"color_1": null,
"color_2": null,
"first_name": "Bella",
"last_name": "Buyer",
"id": "064d6800-fff3-11e5-86aa-5e5517507c66",
"custom_descriptor": null,
"location": "AUS",
"verification_state": "approved",
"held_state": false,
"roles": [
"customer"
],
"dob": "encrypted",
"government_number": "encrypted",
"drivers_license": null,
"flags": {},
"related": {
"addresses": "d2b7dcea-0a4e-4ce4-9259-982619d90ad4"
},
"links": {
"self": "/transactions/7a138862-f821-412d-a91e-367ed7391fe7/users",
"items": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/items",
"card_accounts": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/card_accounts",
"paypal_accounts": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/paypal_accounts",
"bank_accounts": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/bank_accounts",
"wallet_accounts": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/wallet_accounts"
}
}
}
Show the User associated with the Transaction using a given :id.
Endpoint
GET /transactions/:id/users
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Transaction ID |
Shows Transaction Fees
Example Request
transaction.fees.find('2ab6f9f9-5530-42ee-8ebc-453626177c06')
PromisePay::Transaction()->getFee('2ab6f9f9-5530-42ee-8ebc-453626177c06');
var repo = container.Resolve<ITransactionRepository>();
repo.GetFeeForTransactionById("2ab6f9f9-5530-42ee-8ebc-453626177c06");
curl -X "GET" "https://test.api.promisepay.com/transactions/2ab6f9f9-5530-42ee-8ebc-453626177c06/fees" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"fees": {
"id": "e7b030d4-6eb8-416b-bf29-2a766539c1ce",
"uuid": "e7b030d4-6eb8-416b-bf29-2a766539c1ce",
"created_at": "2016-04-19T07:34:15.328Z",
"updated_at": "2016-04-19T07:34:15.328Z",
"fee_list": {
"id": "36020976-f345-4d0f-b860-9c025ccce668",
"name": "Seller Success Fee",
"fee_type": 2,
"amount": 200,
"cap": null,
"min": null,
"max": null,
"to": "seller"
},
"links": {
"self": "/transactions/2ab6f9f9-5530-42ee-8ebc-453626177c06/fees"
}
}
}
Show the Fees associated with the Transaction using a given :id.
Endpoint
GET /transactions/:id/fees
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Transaction ID |
Show Transaction Wallet Account
Example Request
transaction.wallet_account
curl -X "GET" "https://test.api.promisepay.com/transactions/5eb9842f-41a6-4117-a539-79a6b11d1ae5/wallet_accounts" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json"
Example Response (200)
{
"wallet_accounts": {
"id": "4f4a9428-5fdd-4b4a-a7e3-0919cbba5e20",
"active": true,
"created_at": "2016-04-10T15:40:32.345Z",
"updated_at": "2016-04-18T08:20:20.154Z",
"balance": -585,
"currency": "AUD",
"links": {
"self": "/transactions/5eb9842f-41a6-4117-a539-79a6b11d1ae5/wallet_accounts",
"users": "/wallet_accounts/4f4a9428-5fdd-4b4a-a7e3-0919cbba5e20/users",
"disbursements": "/wallet_accounts/4f4a9428-5fdd-4b4a-a7e3-0919cbba5e20/disbursements"
}
}
}
Show the Wallet Account associated with the Transaction using a given :id.
Endpoint
GET /transactions/:id/wallet_accounts
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Transaction ID |
Show Transaction Bank Account
Example Request
transaction.bank_account
curl -X "GET" "https://test.api.promisepay.com/transactions/2f2870f5-7c8f-45cb-8aeb-95190d54f125" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"transactions": {
"id": "2f2870f5-7c8f-45cb-8aeb-95190d54f125",
"created_at": "2016-04-19T08:13:43.963Z",
"updated_at": "2016-04-19T08:13:43.963Z",
"description": "Credit of $50.00 to Item by Debit of $50.00 from Bank Account",
"type": "payment",
"type_method": "direct_debit",
"state": "successful",
"user_id": "064d6800-fff3-11e5-86aa-5e5517507c66",
"account_id": "53e777d5-a2f2-4925-b5cd-029fe8c5d231",
"account_type": "item",
"amount": 5000,
"currency": "AUD",
"debit_credit": "credit",
"related": {
"transactions": [
{
"id": "7fc08177-38c5-4b65-87ea-6546e5360a57",
"account_id": "9fda18e7-b1d3-4a83-830d-0cef0f62cd25",
"account_type": "bank_account",
"user_id": "064d6800-fff3-11e5-86aa-5e5517507c66"
}
]
},
"links": {
"self": "/transactions/2f2870f5-7c8f-45cb-8aeb-95190d54f125",
"users": "/transactions/2f2870f5-7c8f-45cb-8aeb-95190d54f125/users",
"fees": "/transactions/2f2870f5-7c8f-45cb-8aeb-95190d54f125/fees",
"wallet_accounts": "/transactions/2f2870f5-7c8f-45cb-8aeb-95190d54f125/wallet_accounts",
"card_accounts": "/transactions/2f2870f5-7c8f-45cb-8aeb-95190d54f125/card_accounts",
"paypal_accounts": "/transactions/2f2870f5-7c8f-45cb-8aeb-95190d54f125/paypal_accounts",
"bank_accounts": "/transactions/2f2870f5-7c8f-45cb-8aeb-95190d54f125/bank_accounts",
"items": "/transactions/2f2870f5-7c8f-45cb-8aeb-95190d54f125/items"
}
}
}
Show the Bank Account associated with the Transaction using a given :id.
Endpoint
GET /transactions/:id/bank_accounts
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Transaction ID |
Show Transaction Card Account
Example Request
transaction.card_account
curl -X "GET" "https://test.api.promisepay.com/transactions/7a138862-f821-412d-a91e-367ed7391fe7/card_accounts" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"card_accounts": {
"active": true,
"created_at": "2016-04-13T02:59:39.048Z",
"updated_at": "2016-04-18T09:01:43.739Z",
"id": "930a7f78-6bf6-4f33-8cfc-b82c787b5f83",
"currency": "AUD",
"card": {
"type": "visa",
"full_name": "Bella Buyer",
"number": "XXXX-XXXX-XXXX-1111",
"expiry_month": "10",
"expiry_year": "2020"
},
"links": {
"self": "/transactions/7a138862-f821-412d-a91e-367ed7391fe7/card_accounts",
"users": "/card_accounts/930a7f78-6bf6-4f33-8cfc-b82c787b5f83/users"
}
}
}
Show the Card Account associated with the Transaction using a given :id.
Endpoint
GET /transactions/:id/card_accounts
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Transaction ID |
Show Transaction PayPal Account
Example Request
transaction.card_account
curl -X "GET" "https://test.api.promisepay.com/transactions/7a138862-f821-412d-a91e-367ed7391fe7/paypal_accounts" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
Show the PayPal Account associated with the Transaction using a given :id.
Endpoint
GET /transactions/:id/paypal_accounts
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | Transaction ID |
Users
Payments can be paid and received by Users (buyers and/or sellers). Once a user is set up they can be associated with various objects, including Accounts, Items, Companies, and Addresses. There are a number of data requirements when creating Users, notably for sellers.
Create User
Example Request
client.users.create(
id: '5830def0-ffe8-11e5-86aa-5e5517507c66',
first_name: 'Samuel',
last_name: 'Seller',
email: 'samuel.seller@assemblypayments.com',
mobile: '+61491570156',
address_line1: '100 Main Street',
address_line2: '',
state: 'VIC',
city: 'Melbourne',
zip: '3000',
country: 'AUS',
dob:'15/06/1980',
government_number: '10203040',
drivers_license_number: '',
drivers_license_state: '',
ip_address: '',
logo_url: '',
color_1: '',
color_2: ''
)
PromisePay::User()->create(array(
"id" => "5830def0-ffe8-11e5-86aa-5e5517507c66",
"email" => "samuel.seller@assemblypayments.com",
"first_name" => "Samuel",
"last_name" => "Seller",
"mobile" => "+61491570156",
"address_line1" => "100 Main Street",
"address_line2" => "",
"state" => "NSW",
"city" => "Sydney",
"zip" => "2000",
"country" => "AUS",
"dob" => "15/06/1980",
"government_number" => "10203040",
"drivers_license_number" => "",
"drivers_license_state" => "",
"ip_address" => "",
"logo_url" => "",
"color_1" => "",
"color_2" => ""
));
var repo = container.Resolve<IUserRepository>();
repo.CreateUser(new Dictionary<string, object>{
{"id", "5830def0-ffe8-11e5-86aa-5e5517507c66"},
{"first_name", "Samuel"},
{"last_name", "Seller"},
{"email", "samuel.seller@assemblypayments.com"},
{"mobie", "+61491570156"},
{"address_line1", "100 Main Street"},
{"address_line2", ""},
{"state", "VIC"},
{"city", "Melbourne"},
{"zip", "3000"},
{"country", "AUS"},
{"dob","15/06/1980"},
{"government_number", "10203040"},
{"drivers_license_number", ""},
{"drivers_license_state", ""},
{"ip_address", ""},
{"logo_url", ""},
{"color_1", ""},
{"color_2", ""}
});
curl -X "POST" "https://test.api.promisepay.com/users" \
-H "Authorization: Basic YW5kcmV3MkB3ZWJ6ZWxpdGUuY29tLmF1OmUyNGUzMmJkNDBmZGIxNDkyNzllYTBhMzQ1MTVjNTc2" \
-H "Content-Type: application/json" \
-d "{\"id\":\"5830def0-ffe8-11e5-86aa-5e5517507c66\",\"first_name\":\"Samuel\",\"last_name\":\"Seller\",\"email\":\"samuel.seller@assemblypayments.com\",\"mobile\":\"+61491570156\",\"address_line1\":\"100 Main Street\",\"address_line2\":\"\",\"state\":\"VIC\",\"city\":\"Melbourne\",\"zip\":\"3000\",\"country\":\"AUS\",\"dob\":\"15/06/1980\",\"government_number\":\"10203040\",\"drivers_license_number\":\"\",\"drivers_license_state\":\"\",\"ip_address\":\"\",\"logo_url\":\"\",\"color_1\":\"\",\"color_2\":\"\"}"
Example Response (201)
{
"users": {
"created_at": "2016-04-12T08:13:10.665Z",
"updated_at": "2016-04-12T08:13:10.665Z",
"full_name": "Samuel Seller",
"email": "samuel.seller@assemblypayments.com",
"mobile": "+61491570156",
"phone": null,
"logo_url": null,
"color_1": null,
"color_2": null,
"first_name": "Samuel",
"last_name": "Seller",
"id": "5830def0-ffe8-11e5-86aa-5e5517507c66",
"custom_descriptor": null,
"location": "AUS",
"verification_state": "pending",
"held_state": false,
"roles": [
"customer"
],
"dob": "encrypted",
"government_number": "encrypted",
"drivers_license": null,
"flags": {},
"related": {
"addresses": "fe602dcf-4175-4f88-b5be-3beb04092dcd"
},
"links": {
"self": "/users",
"items": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/items",
"card_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/card_accounts",
"paypal_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/paypal_accounts",
"bank_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/bank_accounts",
"wallet_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/wallet_accounts"
}
}
}
Create a User. Users can be associated with Items either as a buyer or a seller.
Users can’t be both the buyer and seller for the same Item.
Note: Some parameters are required for KYC. See our guide on Onboarding a Seller for more information.
Endpoint
POST /users
Parameters
| Parameter | Type | Description |
|---|---|---|
| id required | string | Unique ID that can be generated by the platform. Cannot contain ’.’ character. Contact Assembly support if you want user IDs to be generated automatically. |
| first_name required | string | |
| email required | string | Unique to platform. |
| last_name | string | |
| mobile | string | International number format. Include ’+’ and no spaces. |
| address_line1 | string | |
| address_line2 | string | |
| city | string | |
| state | string | |
| zip | string | Postcode. |
| country required | string | ISO 3166-1 alpha-3 country code (3 char) |
| dob | string | Date of Birth (DD/MM/YYYY). |
| government_number | string | Generic parameter to capture important KYC data. eg. SSN for US users, TFN for AU users. |
| drivers_license_number | string | |
| drivers_license_state | string | |
| ip_address | string | |
| logo_url | string | |
| color_1 | string | |
| color_2 | string | |
| custom_descriptor | string | When custom_descriptors are enabled, this is the information to appear on bundle direct debit statements (which show the buyer’s custom_descriptor) as well as international wire payout, direct credit and PayPal payout statements (which show the seller’s custom_descriptor). |
List Users
Example Request
client.users.find_all
PromisePay::User()->getList(array(
'limit' => 20,
'offset' => 0,
'search' => ''
));
repo = container.Resolve<IUserRepository>();
repo.ListUsers();
curl -X "GET" "https://test.api.promisepay.com/users" \
-H "Authorization: Basic YW5kcmV3MkB3ZWJ6ZWxpdGUuY29tLmF1OmUyNGUzMmJkNDBmZGIxNDkyNzllYTBhMzQ1MTVjNTc2"
Example Response (200)
{
"users": [
{
"id": "064d6800-fff3-11e5-86aa-5e5517507c66",
"full_name": "Bella Buyer",
"first_name": "Bella",
"last_name": "Buyer",
"created_at": "2016-04-12T08:10:47.458Z",
"updated_at": "2016-04-12T08:10:47.458Z",
"email": "bella.buyer@assemblypayments.com",
"mobile": "+61491570159",
"phone": null,
"location": "AUS",
"links": {
"self": "/users/064d6800-fff3-11e5-86aa-5e5517507c66",
"items": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/items",
"card_accounts": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/card_accounts",
"paypal_accounts": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/paypal_accounts",
"bank_accounts": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/bank_accounts",
"wallet_accounts": "/users/064d6800-fff3-11e5-86aa-5e5517507c66/wallet_accounts"
}
},
{
"id": "5830def0-ffe8-11e5-86aa-5e5517507c66",
"full_name": "Samuel Seller",
"first_name": "Samuel",
"last_name": "Seller",
"created_at": "2016-04-12T08:13:10.665Z",
"updated_at": "2016-04-12T08:13:10.665Z",
"email": "samuel.seller@assemblypayments.com",
"mobile": "+61491570156",
"phone": null,
"location": "AUS",
"links": {
"self": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66",
"items": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/items",
"card_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/card_accounts",
"paypal_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/paypal_accounts",
"bank_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/bank_accounts",
"wallet_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/wallet_accounts"
}
}
],
"meta": {
"limit": 10,
"offset": 0,
"total": 2
},
"links": {
"self": "/users"
}
}
Retrieve an ordered and paginated list of existing Users.
Endpoint
GET /users
Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | Integer | Number of records to retrieve. Up to 200. |
| offset | Integer | Number of records to offset. Required for pagination. |
| search | String | search string |
Show User
Example Request
client.users.find('5830def0-ffe8-11e5-86aa-5e5517507c66')
PromisePay::User()->get('5830def0-ffe8-11e5-86aa-5e5517507c66');
var repo = container.Resolve<IUserRepository>();
repo.GetUserById("5830def0-ffe8-11e5-86aa-5e5517507c66");
curl -X "GET" "https://test.api.promisepay.com/users/5830def0-ffe8-11e5-86aa-5e5517507c66" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"users": {
"created_at": "2016-04-12T08:13:10.665Z",
"updated_at": "2016-04-12T08:13:10.665Z",
"full_name": "Samuel Seller",
"email": "samuel.seller@assemblypayments.com",
"mobile": "+61491570156",
"phone": null,
"logo_url": null,
"color_1": null,
"color_2": null,
"first_name": "Samuel",
"last_name": "Seller",
"id": "5830def0-ffe8-11e5-86aa-5e5517507c66",
"custom_descriptor": null,
"location": "AUS",
"verification_state": "pending",
"held_state": false,
"roles": [
"customer"
],
"dob": "encrypted",
"government_number": "encrypted",
"drivers_license": null,
"flags": {},
"related": {
"addresses": "fe602dcf-4175-4f88-b5be-3beb04092dcd"
},
"links": {
"self": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66",
"items": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/items",
"card_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/card_accounts",
"paypal_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/paypal_accounts",
"bank_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/bank_accounts",
"wallet_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/wallet_accounts"
}
}
}
Show details of a specific User using a given :id.
Endpoint
GET /users/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | User ID |
Update User
Example Request
client.users.update(
id: '5830def0-ffe8-11e5-86aa-5e5517507c66',
first_name: 'Samuel',
last_name: 'Seller',
email: 'samuel.seller@assemblypayments.com',
mobie: '+61491570156',
address_line1: '100 Main Street',
address_line2: '',
state: 'VIC',
city: 'Melbourne',
zip: '3000',
country: 'AUS',
custom_descriptor: 'Sam Garden Jobs',
dob:'15/06/1980',
government_number: '10203040',
drivers_license_number: '',
drivers_license_state: '',
ip_address: '',
logo_url: '',
color_1: '',
color_2: ''
)
PromisePay::User()->update("5830def0-ffe8-11e5-86aa-5e5517507c66", array(
"email" => "samuel.seller@assemblypayments.com",
"first_name" => "Samuel",
"last_name" => "Seller",
"mobile" => "+61491570156",
"address_line1" => "100 Main Street",
"address_line2" => "",
"state" => "VIC",
"city" => "Melbourne",
"zip" => "3000",
"country" => "AUS",
"custom_descriptor" => "Sam Garden Jobs",
"dob" => "15/06/1980",
"government_number" => "10203040",
"drivers_license_number" => "",
"drivers_license_state" => "",
"ip_address" => "",
"logo_url" => "",
"color_1" => "",
"color_2" => ""
));
var repo = container.Resolve<IUserRepository>();
repo.UpdateUserById(new Dictionary<string,object){
{"id", "5830def0-ffe8-11e5-86aa-5e5517507c66"},
{"first_name", "Samuel"},
{"last_name", "Seller"},
{"email", "samuel.seller@assemblypayments.com"},
{"mobie", "+61491570156"},
{"address_line1", "100 Main Street"},
{"address_line2", ""},
{"state", "VIC"},
{"city", "Melbourne"},
{"zip", "3000"},
{"country", "AUS"},
{"custom_descriptor", "Sam Garden Jobs"},
{"dob","15/06/1980"},
{"government_number", "10203040"},
{"drivers_license_number", ""},
{"drivers_license_state", ""},
{"ip_address", ""},
{"logo_url", ""},
{"color_1", ""},
{"color_2", ""}
});
curl -X "PATCH" "https://test.api.promisepay.com/users/5830def0-ffe8-11e5-86aa-5e5517507c66" \
-H "Content-Type: application/json" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-d "{\"first_name\":\"Samuel\",\"last_name\":\"Seller\",\"email\":\"samuel.seller@assemblypayments.com\",\"mobile\":\"+61491570156\",\"address_line1\":\"100 Main Street\",\"address_line2\":\"\",\"state\":\"VIC\",\"city\":\"Melbourne\",\"zip\":\"3000\",\"country\":\"AUS\",\"custom_descriptor\":\"Sam Garden Jobs\", \"dob\":\"15/06/1980\",\"government_number\":\"10203040\",\"drivers_license_number\":\"\",\"drivers_license_state\":\"\",\"ip_address\":\"\",\"logo_url\":\"\",\"color_1\":\"\",\"color_2\":\"\"}"
Example Response (200)
{
"users": {
"created_at": "2016-04-12T08:13:10.665Z",
"updated_at": "2016-04-12T08:13:10.665Z",
"full_name": "Samuel Seller",
"email": "samuel.seller@assemblypayments.com",
"mobile": "+61491570156",
"phone": null,
"logo_url": null,
"color_1": null,
"color_2": null,
"first_name": "Samuel",
"last_name": "Seller",
"id": "5830def0-ffe8-11e5-86aa-5e5517507c66",
"custom_descriptor": "Sam Garden Jobs"
"location": "AUS",
"verification_state": "pending",
"held_state": false,
"roles": [
"customer"
],
"dob": "encrypted",
"government_number": "encrypted",
"drivers_license": null,
"flags": {},
"related": {
"addresses": "fe602dcf-4175-4f88-b5be-3beb04092dcd"
},
"links": {
"self": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66",
"items": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/items",
"card_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/card_accounts",
"paypal_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/paypal_accounts",
"bank_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/bank_accounts",
"wallet_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/wallet_accounts"
}
}
}
Update an existing User’s attributes using a given :id.
Endpoint
PATCH /users/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id required | string | Unique ID that can be generated by the platform. Cannot contain ’.’ character. |
| first_name | string | |
| string | Unique to platform. | |
| last_name | string | |
| mobile | string | International number format. Include ’+’ and no spaces. |
| address_line1 | string | |
| address_line2 | string | |
| city | string | |
| state | string | |
| zip | string | Postcode. |
| country | string | ISO 3166-1 alpha-3 country code (3 char) |
| dob | string | Date of Birth (DD/MM/YYYY). |
| government_number | string | Generic parameter to capture important KYC data. eg. SSN for US users, TFN for AU users. |
| drivers_license_number | string | |
| drivers_license_state | string | |
| ip_address | string | |
| logo_url | string | |
| color_1 | string | |
| color_2 | string | |
| custom_descriptor | string | When custom_descriptors are enabled, this is the information to appear on bundle direct debit statements (which show the buyer’s custom_descriptor) as well as international wire payout, direct credit and PayPal payout statements (which show the seller’s custom_descriptor). |
Show User Bank Account
Example Request
user.bank_account.find('5830def0-ffe8-11e5-86aa-5e5517507c66')
PromisePay::User()->getListOfBankAccounts('5830def0-ffe8-11e5-86aa-5e5517507c66');
var repo = container.Resolve<IUserRepository>();
repo.ListBankAccountsForUserById("5830def0-ffe8-11e5-86aa-5e5517507c66");
curl -X "GET" "https://test.api.promisepay.com/users/5830def0-ffe8-11e5-86aa-5e5517507c66/bank_accounts" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"bank_accounts": {
"id": 46deb476-c1a6-41eb-8eb7-26a695bbe5bc,
"active": true,
"created_at": "2016-04-12T09:20:38.540Z",
"updated_at": "2016-04-12T09:20:38.540Z",
"verification_status": "not_verified",
"currency": "AUD",
"bank": {
"bank_name": "Bank of Australia",
"country": "AUS",
"account_name": "Samuel Seller",
"routing_number": "XXXXX3",
"account_number": "XXX234",
"holder_type": "personal",
"account_type": "checking",
"direct_debit_authority_status": null
},
"links": {
"self": "/users/46deb476-c1a6-41eb-8eb7-26a695bbe5bc/bank_accounts",
"users": "/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc/users",
"direct_debit_authorities": "/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc/direct_debit_authorities"
}
}
}
Shows the user’s active bank account using a given :id.
Endpoint
GET /users/:id/bank_accounts
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | User ID |
Show User Card Account
Example Request
user.card_account.find('5830def0-ffe8-11e5-86aa-5e5517507c66')
PromisePay::User()->getListOfCardAccounts('5830def0-ffe8-11e5-86aa-5e5517507c66');
var repo = container.Resolve<IUserRepository>();
repo.ListCardAccountsForUserById("5830def0-ffe8-11e5-86aa-5e5517507c66");
curl -X "GET" "https://test.api.promisepay.com/users/5830def0-ffe8-11e5-86aa-5e5517507c66/card_accounts" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"card_accounts": {
"active": true,
"created_at": "2016-04-17T13:03:12.294Z",
"updated_at": "2016-04-17T13:03:12.294Z",
"id": "fa282b54-4728-4732-82e2-75bded33993e",
"currency": "AUD",
"card": {
"type": "visa",
"full_name": "Bella Buyer",
"number": "XXXX-XXXX-XXXX-1111",
"expiry_month": "10",
"expiry_year": "2020"
},
"links": {
"self": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/card_accounts",
"users": "/card_accounts/fa282b54-4728-4732-82e2-75bded33993e/users"
}
}
}
Show the user’s active card account using a given :id.
Endpoint
GET /users/:id/card_accounts
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | User ID |
Show User PayPal Account
Example Request
user.paypal_account.find('5830def0-ffe8-11e5-86aa-5e5517507c66')
PromisePay::User()->getListOfPayPalAccounts('5830def0-ffe8-11e5-86aa-5e5517507c66');
var repo = container.Resolve<IUserRepository>();
repo.ListPayPalAccountsForUserById("5830def0-ffe8-11e5-86aa-5e5517507c66");
curl -X "GET" "https://test.api.promisepay.com/users/5830def0-ffe8-11e5-86aa-5e5517507c66/paypal_accounts" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"paypal_accounts": {
"active": true,
"created_at": "2016-04-13T06:33:21.633Z",
"updated_at": "2016-04-13T06:33:21.633Z",
"id": "7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b",
"currency": "AUD",
"paypal": {
"email": "samuel.seller@assemblypayments.com"
},
"links": {
"self": "/users/7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b/paypal_accounts",
"users": "/paypal_accounts/7efa449a-29b6-4ab3-83d6-03e7eaa4bf7b/users"
}
}
}
Show a User’s PayPal Account using a given :id.
Endpoint
GET /users/:id/paypal_accounts
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | User ID |
Show User Wallet Account
Example Request
Not available.
Not available.
Not available.
curl -X "GET" "https://test.api.promisepay.com/users/5830def0-ffe8-11e5-86aa-5e5517507c66/wallet_accounts" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"wallet_accounts": {
"id": "385b50bb-237a-42cb-9382-22953e191ae6",
"active": true,
"created_at": "2016-04-12T08:13:10.709Z",
"updated_at": "2016-04-12T09:22:31.645Z",
"balance": 0,
"currency": "AUD",
"links": {
"self": "/users/385b50bb-237a-42cb-9382-22953e191ae6/wallet_accounts",
"users": "/wallet_accounts/385b50bb-237a-42cb-9382-22953e191ae6/users",
"batch_transactions": "/wallet_accounts/385b50bb-237a-42cb-9382-22953e191ae6/batch_transactions",
"transactions": "/wallet_accounts/385b50bb-237a-42cb-9382-22953e191ae6/transactions"
}
}
}
Show the User’s Wallet Account using a given :id.
Endpoint
GET /users/:id/wallet_accounts
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | User ID |
Set User Disbursement Account
Example Request
user.disbursement_account('46deb476-c1a6-41eb-8eb7-26a695bbe5bc')
PromisePay::User()->setDisbursementAccount('5830def0-ffe8-11e5-86aa-5e5517507c66', ['account_id' => '46deb476-c1a6-41eb-8eb7-26a695bbe5bc']);
var repo = container.Resolve<IUserRepository>();
repo.SetDisbursementAccount("5830def0-ffe8-11e5-86aa-5e5517507c66", "46deb476-c1a6-41eb-8eb7-26a695bbe5bc");
curl -X "PATCH" "https://test.api.promisepay.com/users/5830def0-ffe8-11e5-86aa-5e5517507c66/disbursement_account" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-F "account_id=46deb476-c1a6-41eb-8eb7-26a695bbe5bc"
Example Response (200)
{
"users": {
"created_at": "2016-04-12T08:13:10.665Z",
"updated_at": "2016-04-12T09:07:55.083Z",
"full_name": "Samuel Seller",
"email": "samuel.seller@assemblypayments.com",
"mobile": "+61491570156",
"phone": null,
"logo_url": null,
"color_1": null,
"color_2": null,
"first_name": "Samuel",
"last_name": "Seller",
"id": "5830def0-ffe8-11e5-86aa-5e5517507c66",
"custom_descriptor": "Sam Garden Jobs",
"location": "AUS",
"verification_state": "approved",
"held_state": false,
"dob": "encrypted",
"government_number": "encrypted",
"drivers_license": null,
"flags": {},
"related": {
"addresses": "fe602dcf-4175-4f88-b5be-3beb04092dcd",
"payout_account": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc"
},
"links": {
"self": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/disbursement_account",
"items": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/items",
"card_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/card_accounts",
"paypal_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/paypal_accounts",
"bank_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/bank_accounts",
"wallet_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/wallet_accounts"
}
}
}
Set the User’s Disbursement Account using a given User :id and one of either a Bank Account :account_id or a PayPal Account :account_id.
Endpoint
PATCH /users/:id/disbursement_account
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | User ID |
| account_id | String | Account ID (Bank account or PayPal account) |
List User Items
Example Request
user.items.find('5830def0-ffe8-11e5-86aa-5e5517507c66')
PromisePay::User()->getListOfItems('5830def0-ffe8-11e5-86aa-5e5517507c66');
var repo = container.Resolve<IUserRepository>();
repo.ListItemsForUserById("5830def0-ffe8-11e5-86aa-5e5517507c66");
curl -X "GET" "https://test.api.promisepay.com/users/5830def0-ffe8-11e5-86aa-5e5517507c66/items" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"items": [
{
"id": "e57120ea-053d-11e6-b512-3e1d05defe78",
"name": "Landscaping Job #002",
"description": "Removal of weeds.",
"created_at": "2016-04-18T08:17:32.708Z",
"updated_at": "2016-04-18T08:20:20.374Z",
"state": "completed",
"payment_type_id": 1,
"status": 22500,
"amount": 10000,
"deposit_reference": "100014013962667",
"buyer_name": "Bella Buyer",
"buyer_country": "AUS",
"buyer_email": "bella.buyer@assemblypayments.com",
"seller_name": "Samuel Seller",
"seller_country": "AUS",
"seller_email": "samuel.seller@assemblypayments.com",
"currency": "AUD",
"links": {
"self": "/items/e57120ea-053d-11e6-b512-3e1d05defe78",
"buyers": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/buyers",
"sellers": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/sellers",
"status": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/status",
"fees": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/fees",
"transactions": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/transactions",
"batch_transactions": "items/e57120ea-053d-11e6-b512-3e1d05defe78/batch_transactions",
"wire_details": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/wire_details",
"bpay_details": "/items/e57120ea-053d-11e6-b512-3e1d05defe78/bpay_details"
}
},
{
"id": "100fd4a0-0538-11e6-b512-3e1d05defe78",
"name": "Landscaping Job #001",
"description": "Planting of natives, removal of tree stump.",
"created_at": "2016-04-18T07:37:29.580Z",
"updated_at": "2016-04-18T08:15:02.822Z",
"state": "completed",
"payment_type_id": 2,
"status": 22500,
"amount": 25000,
"deposit_reference": "100014013961629",
"buyer_name": "Bella Buyer",
"buyer_country": "AUS",
"buyer_email": "bella.buyer@assemblypayments.com",
"seller_name": "Samuel Seller",
"seller_country": "AUS",
"seller_email": "samuel.seller@assemblypayments.com",
"currency": "AUD",
"links": {
"self": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78",
"buyers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/buyers",
"sellers": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/sellers",
"status": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/status",
"fees": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/fees",
"transactions": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/transactions",
"batch_transactions": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/batch_transactions",
"wire_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/wire_details",
"bpay_details": "/items/100fd4a0-0538-11e6-b512-3e1d05defe78/bpay_details"
}
}
],
"links": {
"self": "/items"
},
"meta": {
"limit": 10,
"offset": 0,
"total": 2
}
}
Retrieve an ordered and paginated list of existing Items the User is associated with using a given :id.
Endpoint
GET /users/:id/items
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | User ID |
Verify User
Example request
curl -X "PATCH" "https://test.api.promisepay.com/users/5830def0-ffe8-11e5-86aa-5e5517507c66?type=identity_verified" \
-H "authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
Example response
{
"users": {
"created_at": "2016-04-12T08:13:10.665Z",
"updated_at": "2016-04-12T08:13:10.665Z",
"full_name": "Samuel Seller",
"email": "samuel.seller@assemblypayments.com",
"mobile": "+61491570156",
"phone": null,
"logo_url": null,
"color_1": null,
"color_2": null,
"first_name": "Samuel",
"last_name": "Seller",
"id": "5830def0-ffe8-11e5-86aa-5e5517507c66",
"custom_descriptor": null,
"location": "AUS",
"verification_state": "approved",
"held_state": false,
"roles": [
"customer"
],
"dob": "encrypted",
"government_number": "encrypted",
"drivers_license": null,
"flags": {},
"related": {
"addresses": "fe602dcf-4175-4f88-b5be-3beb04092dcd"
},
"links": {
"self": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66",
"items": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/items",
"card_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/card_accounts",
"paypal_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/paypal_accounts",
"bank_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/bank_accounts",
"wallet_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/wallet_accounts"
}
}
}
Sets a user’s KYC state to approved on pre-live given the user :id
Ensure that a user has the required KYC information before using this call. Otherwise, the call will fail. See Onboarding a Seller for the parameters required for KYC approval.
Note: This API call will only work in our pre-live environment. The KYC workflow holds for all users in production.
Endpoint
PATCH /users/:id?type=identity_verified
Parameters
| Parameter | Type | Description |
|---|---|---|
| id required | string | User ID |
Wallet Accounts
Wallet Accounts can be used as a funding source for the payment of Items. They need to be funded from a Bank Account or from the proceeds of other Item transactions.
Wallet Accounts are automatically created for each User. You need to store the :id against the user on your platform. When using a Wallet Account as a funding source, the relevant :id is passed to the make_payment Item Action.
Funds that are released from an Item to the user allocated as the seller are placed in the User’s Wallet Account.
Show Wallet Account
Example Request
client.wallet_accounts.find('385b50bb-237a-42cb-9382-22953e191ae6')
curl -X "GET" "https://test.api.promisepay.com/wallet_accounts/385b50bb-237a-42cb-9382-22953e191ae6" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
Example Response (200)
{
"wallet_accounts": {
"id": "385b50bb-237a-42cb-9382-22953e191ae6",
"active": true,
"created_at": "2016-04-12T08:13:10.709Z",
"updated_at": "2016-04-12T09:22:31.645Z",
"balance": 0,
"currency": "AUD",
"links": {
"self": "/wallet_accounts/385b50bb-237a-42cb-9382-22953e191ae6",
"users": "/wallet_accounts/385b50bb-237a-42cb-9382-22953e191ae6/users",
"disbursements": "/wallet_accounts/385b50bb-237a-42cb-9382-22953e191ae6/disbursements"
}
}
}
Show details of a specific Wallet Account using a given :id.
Endpoint
GET /wallet_accounts/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | account ID |
Withdraw Funds
Example Request
wallet_accounts.withdraw(
id: '385b50bb-237a-42cb-9382-22953e191ae6'
account_id: '46deb476-c1a6-41eb-8eb7-26a695bbe5bc',
amount: 10000
)
curl -X "POST" "https://test.api.promisepay.com/wallet_accounts/385b50bb-237a-42cb-9382-22953e191ae6/withdraw" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"amount\":\"10000\",\"account_id\":\"46deb476-c1a6-41eb-8eb7-26a695bbe5bc\"}"
Example Response (201)
{
"disbursements": {
"id": "ad688d54-6791-4f1d-add7-88fbd89b70d1",
"amount": 10000,
"currency": "AUD",
"batch_id": null,
"created_at": "2016-04-26T08:56:25.035Z",
"updated_at": "2016-04-26T08:56:25.035Z",
"state": "pending",
"to": "Bank Account",
"bank_name": "Bank of Australia",
"bank_account_name": "Samuel Seller",
"bank_account_number": "XXX234",
"bank_routing_number": "XXXXX3",
"links": {
"transactions": "/disbursements/ad688d54-6791-4f1d-add7-88fbd89b70d1/transactions",
"wallet_accounts": "/disbursements/ad688d54-6791-4f1d-add7-88fbd89b70d1/wallet_accounts",
"bank_accounts": "/disbursements/ad688d54-6791-4f1d-add7-88fbd89b70d1/bank_accounts",
"paypal_accounts": "/disbursements/ad688d54-6791-4f1d-add7-88fbd89b70d1/paypal_accounts",
"items": "/disbursements/ad688d54-6791-4f1d-add7-88fbd89b70d1/items",
"users": "/disbursements/ad688d54-6791-4f1d-add7-88fbd89b70d1/users"
}
}
}
Withdraw funds from a Wallet Account to a specified disbursement account.
Endpoint
POST /wallet_accounts/:id/withdraw
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | account ID |
| account_id | String | Account to withdraw to. |
| amount | Integer | Amount (in cents) to withdraw. |
Deposit Funds
Example Request
wallet_accounts.deposit(
id: '385b50bb-237a-42cb-9382-22953e191ae6'
account_id: '46deb476-c1a6-41eb-8eb7-26a695bbe5bc',
amount: 5000
)
curl -X "POST" "https://test.api.promisepay.com/wallet_accounts/385b50bb-237a-42cb-9382-22953e191ae6/deposit" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"amount\":\"5000\",\"account_id\":\"46deb476-c1a6-41eb-8eb7-26a695bbe5bc\"}"
Example Response (200)
{
"disbursements": {
"id": "210bc8ba-d646-4e35-b029-a1959e4ca8c5",
"amount": 5000,
"currency": "AUD",
"batch_id": null,
"created_at": "2016-04-26T09:01:02.199Z",
"updated_at": "2016-04-26T09:01:02.199Z",
"state": "pending",
"links": {
"transactions": "/disbursements/210bc8ba-d646-4e35-b029-a1959e4ca8c5/transactions",
"wallet_accounts": "/disbursements/210bc8ba-d646-4e35-b029-a1959e4ca8c5/wallet_accounts",
"bank_accounts": "/disbursements/210bc8ba-d646-4e35-b029-a1959e4ca8c5/bank_accounts",
"paypal_accounts": "/disbursements/210bc8ba-d646-4e35-b029-a1959e4ca8c5/paypal_accounts",
"items": "/disbursements/210bc8ba-d646-4e35-b029-a1959e4ca8c5/items",
"users": "/disbursements/210bc8ba-d646-4e35-b029-a1959e4ca8c5/users"
}
}
}
Deposit funds to a Wallet Account from a specified payment account.
Endpoint
POST /wallet_accounts/:id/deposit
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | account ID |
| account_id | String | Account to deposit from. |
| amount | Integer | Amount (in cents) to deposit. |
Show Wallet Account User
Example Request
wallet_accounts.user.find('385b50bb-237a-42cb-9382-22953e191ae6')
curl -X "GET" "https://test.api.promisepay.com/wallet_accounts/385b50bb-237a-42cb-9382-22953e191ae6/users" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
Example Response (200)
{
"users": {
"created_at": "2016-04-12T08:13:10.665Z",
"updated_at": "2016-04-12T09:07:55.083Z",
"full_name": "Samuel Seller",
"email": "samuel.seller@assemblypayments.com",
"mobile": "+61491570156",
"phone": null,
"logo_url": null,
"color_1": null,
"color_2": null,
"first_name": "Samuel",
"last_name": "Seller",
"id": "5830def0-ffe8-11e5-86aa-5e5517507c66",
"custom_descriptor": null,
"location": "AUS",
"verification_state": "approved",
"held_state": false,
"roles": [
"customer"
],
"dob": "encrypted",
"government_number": "encrypted",
"drivers_license": null,
"flags": {},
"related": {
"addresses": "fe602dcf-4175-4f88-b5be-3beb04092dcd",
"payout_account": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc"
},
"links": {
"self": "/wallet_accounts/385b50bb-237a-42cb-9382-22953e191ae6/users",
"items": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/items",
"card_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/card_accounts",
"paypal_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/paypal_accounts",
"bank_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/bank_accounts",
"wallet_accounts": "/users/5830def0-ffe8-11e5-86aa-5e5517507c66/wallet_accounts"
}
}
}
Show the User the Wallet Account is associated with using a given :id.
Endpoint
GET /wallet_accounts/:id/users
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | String | account ID |
Configurations
Different feature configurations exist in your marketplace which define how it behaves in different areas, such as transactions, payments and other system settings.
For example, the partial_refunds feature can be configured to either allow or disallow partial refunds on a country, user or item.
Assembly sets the feature configurations of your marketplace according to your business preferences. You can also set some basic configurations on your marketplace.
Create Configuration
Example Request
client.configurations.create(
name: 'auto_request_payment',
enabled: false)
PromisePay::Configurations()->create(array(
'name' => 'auto_request_payment',
'enabled' => false,
));
var repo = container.Resolve<IConfigurationRepository>();
repo.Create(new Dictionary<string,object>{
{"name", "auto_request_payment"},
{"enabled", false}
});
curl -X "POST" "https://test.api.promisepay.com/configurations" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"name\":\"auto_request_payment\",\"enabled\":\"false\",\"user_id\":\"\",\"country\":\"\",\"item_id\":\"\",\"options\":\"\",\"min\":\"\",\"max\":\"\"}"
Example Response (200)
{
"feature_configurations": {
"name": "auto_request_payment",
"enabled": false,
"min": null,
"max": null,
"id": b1eced95-4e2d-4afd-bac2-ab0801209c5f,
"user_id": null,
"country": null,
"item_id": null,
"options": null,
"links": {
"self": "/configurations/b1eced95-4e2d-4afd-bac2-ab0801209c5f"
}
}
}
Creates a new configuration based on the parameters defined
Endpoint
POST /configurations
Parameters
| Parameter | Type | Description |
|---|---|---|
| name required | string | Name of feature |
| enabled | Boolean | Toggles enabling of feature (true or false) |
| user_id | string | User ID on which the configuration is in effect |
| country | string | Country in which the configuration is in effect |
| item_id | string | Item ID on which the configuration is in effect |
| options | JSON | Hash of options for the feature |
| min | string | Minimum value (for future use) |
| max | string | Maximum value (for future use) |
List Configurations
Example Request
client.configurations.find_all
PromisePay::Configurations()->getList();
var repo = container.Resolve<IConfigurationRepository>();
repo.List();
curl -X "GET" "https://test.api.promisepay.com/configurations" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
-H "Content-Type: application/json" \
-d "{\"search\":\"\",\"user_id\":\"\",\"item_id\":\"\",\"country\":\"\"}"
Example Response (200)
{
"feature_configurations": [
{
"name": "auto_request_payment",
"enabled": false,
"min": null,
"max": null,
"id": "b1eced95-4e2d-4afd-bac2-ab0801209c5f",
"user_id": null,
"country": null,
"item_id": null,
"options": null
},
{
"name": "partial_refunds",
"enabled": false,
"min": null,
"max": null,
"id": "71131135-5dd0-4641-8f11-9855fa68e608",
"user_id": null,
"country": null,
"item_id": null,
"options": null
}
],
"meta": {
"limit": 10,
"offset": 0,
"total": 2
}
}
Retrieves an ordered list of existing configurations based on the search query and user, item or country specified
Endpoint
GET /configurations
Parameters
| Parameter | Type | Description |
|---|---|---|
| search | string | Search string |
| user_id | string | User ID to specify, if any |
| item_id | string | Item ID to specify, if any |
| country | string | Country to specify, if any |
Show Configuration
Example Request
client.configurations.find('b1eced95-4e2d-4afd-bac2-ab0801209c5f')
PromisePay::Configurations()->get('b1eced95-4e2d-4afd-bac2-ab0801209c5f');
var repo = container.Resolve<IConfigurationRepository>();
repo.Show("b1eced95-4e2d-4afd-bac2-ab0801209c5f");
curl -X "GET" "https://test.api.promisepay.com/configurations/b1eced95-4e2d-4afd-bac2-ab0801209c5f" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"feature_configurations": {
"name": "auto_request_payment",
"enabled": false,
"min": null,
"max": null,
"id": "b1eced95-4e2d-4afd-bac2-ab0801209c5f",
"user_id": null,
"country": null,
"item_id": null,
"options": null,
"links": {
"self": "/configurations/b1eced95-4e2d-4afd-bac2-ab0801209c5f"
}
}
}
Shows details of a specific configuration using a given :id
Endpoint
GET /configurations/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | Configuration ID |
Update Configuration
Example Request
config.update(enabled: true)
PromisePay::Configurations()->update(array(
'id' => 'b1eced95-4e2d-4afd-bac2-ab0801209c5f',
'name' => 'auto_request_payment',
'enabled' => true,
));
var repo = container.Resolve<IConfigurationRepository>();
repo.Update(new Dictionary<string,object>{
{"id","b1eced95-4e2d-4afd-bac2-ab0801209c5f"},
{"name","auto_request_payment"},
{"enabled","true"}
});
curl -X "PATCH" "https://test.api.promisepay.com/configurations/b1eced95-4e2d-4afd-bac2-ab0801209c5f" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
-H "Content-Type: application/json" \
-d "{\"name\":\"auto_request_payment\",\"enabled\":\"true\",\"user_id\":\"\",\"country\":\"\",\"item_id\":\"\",\"options\":\"\",\"min\":\"\",\"max\":\"\"}"
Example Response (200)
{
"feature_configurations": {
"name": "auto_request_payment",
"enabled": true,
"min": null,
"max": null,
"id": "b1eced95-4e2d-4afd-bac2-ab0801209c5f",
"user_id": null,
"country": null,
"item_id": null,
"options": null,
"links": {
"self": "/configurations/b1eced95-4e2d-4afd-bac2-ab0801209c5f"
}
}
}
Updates an existing configuration using a given :id
Endpoint
PATCH /configurations/:id
Parameters
| Parameter | Type | Definition |
|---|---|---|
| id required | string | ID of the configuration to be updated |
| name required | string | Name of feature |
| enabled | Boolean | Toggles enabling of feature (true or false) |
| user_id | string | User ID on which the configuration is in effect |
| country | string | Country in which the configuration is in effect |
| item_id | string | Item ID on which the configuration is in effect |
| options | JSON | Hash of options for the feature |
| min | string | Minimum value (future use) |
| max | string | Maximum value (future use) |
Delete Configuration
Example Request
config.delete
PromisePay::Configurations()->delete('b1eced95-4e2d-4afd-bac2-ab0801209c5f');
var repo = container.Resolve<IConfigurationRepository>();
repo.Delete("b1eced95-4e2d-4afd-bac2-ab0801209c5f");
curl -X "DELETE" "https://test.api.promisepay.com/configurations/b1eced95-4e2d-4afd-bac2-ab0801209c5f" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"feature_configurations": {
"name": "auto_request_payment",
"enabled": true,
"min": null,
"max": null,
"id": "b1eced95-4e2d-4afd-bac2-ab0801209c5f",
"user_id": null,
"country": null,
"item_id": null,
"options": null,
"links": {
"self": "/configurations/b1eced95-4e2d-4afd-bac2-ab0801209c5f"
}
}
}
Deletes an existing configuration using a given :id
Endpoint
DELETE /configurations/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | ID of the configuration to be deleted |
Payment Restrictions
Different payment restrictions exist in your marketplace which define the modes of payment permissible both for the buyers and sellers in it.
Payment restrictions can also be defined by its amount, country, user or item.
Assembly sets the payment restrictions of your marketplace according to your business preferences.
List Payment Restrictions
Example Request
client.payment_restrictions.find_all
PromisePay::PaymentRestrictions()->getList();
var repo = container.Resolve<IRestrictionRepository>();
repo.List();
curl -X "GET" "https://test.api.promisepay.com/payment_restrictions" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
-H "Content-Type: application/json" \
-d "{\"search\":\"\",\"user_id\":\"\",\"item_id\":\"\",\"country\":\"\"}"
Example Response (200)
{
"payment_restrictions": [
{
"name": "credit_card",
"direction": "out",
"enabled": false,
"min": null,
"max": null,
"user_role": null,
"id": "12a7732c-87a8-432d-a814-b53c1586ec3c",
"user_id": null,
"country": null,
"item_id": null
},
{
"name": "credit_card",
"direction": "in",
"enabled": false,
"min": null,
"max": null,
"user_role": null,
"id": "43c98422-0ff2-47bf-8feb-c6858a304770",
"user_id": null,
"country": null,
"item_id": null
}
],
"meta": {
"limit": 10,
"offset": 0,
"total": 2
}
}
Retrieves an ordered list of existing payment restrictions based on the search query and parameters specified
Endpoint
GET /payment_restrictions
Parameters
| Parameter | Type | Description |
|---|---|---|
| search | string | Search string |
| user_id | string | User ID to specify, if any |
| item_id | string | Item ID to specify, if any |
| country | string | Country to specify, if any |
Show Payment Restriction
Example Request
client.payment_restrictions.find('12a7732c-87a8-432d-a814-b53c1586ec3c')
PromisePay::PaymentRestrictions()->get('12a7732c-87a8-432d-a814-b53c1586ec3c');
var repo = container.Resolve<IRestrictionRepository>();
repo.Show("12a7732c-87a8-432d-a814-b53c1586ec3c");
curl -X "GET" "https://test.api.promisepay.com/payment_restrictions/12a7732c-87a8-432d-a814-b53c1586ec3c" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"payment_restrictions": {
"name": "credit_card",
"direction": "out",
"enabled": false,
"min": null,
"max": null,
"user_role": null,
"id": "12a7732c-87a8-432d-a814-b53c1586ec3c",
"user_id": null,
"country": null,
"item_id": null,
"links": {
"self": "/payment_restrictions/12a7732c-87a8-432d-a814-b53c1586ec3c"
}
}
}
Shows details of a specific payment restriction using a given :id
Endpoint
GET /payment_restrictions/:id
Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | Payment restriction ID |
Tools
Various functions that can be used for monitoring, testing and miscellaneous purposes within your platform.
Health check
Example Request
client.tools.health_check
curl -X "GET" "https://test.api.promisepay.com/status" \
-H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="
Example Response (200)
{
"status": "healthy"
}
Displays a health check of the Assembly service.
Endpoint
GET /status
Reference Data
Test data can be used in the Assembly pre-live environment. Use this in conjunction with Item and User statuses to complete an end-to-end integration in pre-live.
Credit Card Data
Use the following credit card details to simulate credit card transactions. Transactions using this credit card with return success.
| Parameter | Value | Description |
|---|---|---|
| Successful Visa | 4111 1111 1111 1111 | |
| Declined Visa | 4012 8888 8888 1881 | |
| Declined MasterCard | 5105 1051 0510 5100 | |
| Payment Held Card Number | 5555 5555 5555 4444 | Will progress the Item to the payment_held state. |
| Expiry date (any date in the future) | 09/19 | |
| CVV/CVC | 123 |
Mobile Data
Use the following mobile details when required to provide test mobile details. Any valid international format mobile number will be successful.
| Parameter | Value |
|---|---|
| Mobile | Any valid number (eg. +61 412 341 234) |
| Mobile pin | 123456 |
Bank and PayPal Data
There is no test data for bank accounts or PayPal accounts in the pre-live environment. You can provide dummy data to emulate banking information, and a fake email address to represent a PayPal email.
Item States
The following table lists the states available that an item can assume on your platform.
| Item State | Code | Description |
|---|---|---|
| pending | 22000 | Transaction has not started yet, no payment received or requested. |
| payment_required | 22100 | Payment has been requested by the seller to the buyer. |
| wire_pending | 22110 | The buyer has acknowledged that they are wiring the funds in, they are on their way. |
| paypal_pending | 22111 | The buyer has acknowledged that they have paid by PayPal, the funds are being cleared by PayPal. |
| payment_pending | 22150 | Direct debit payment has been triggered, awaiting for these funds to clear. |
| payment_held | 22175 | Payment has been held as automatic triggers have been alerted. This will go through a manual review to move on to payment_deposited, or fraud_hold. |
| payment_authorized | 22180 | A credit card payment has been authorized for capture. |
| voided | 22195 | A previous credit card payment authorization has been voided. |
| fraud_hold | 22190 | Payment is acknowledged as fraud, these funds will attempt to be refunded. |
| payment_deposited | 22200 | Payment has been successfully received in our escrow vault. |
| work_completed | 22300 | Seller has requested release, they have delivered the goods or service. |
| problem_flagged | 22400 | A dispute has been raised by either the buyer/seller, transaction is on hold until it is resolved. |
| problem_resolve_requested | 22410 | The other party (who didn’t raise the dispute) has requested that the dispute should be resolved. |
| problem_escalated | 22420 | The dispute has not been resolved and has been escalated. This will go into a process of third party litigation. |
| completed | 22500 | The Item is completed, funds have been released. |
| cancelled | 22575 | The Item is cancelled and can no longer be accessed. |
| refunded | 22600 | The funds have been refunded to the funding source of the buyer. |
| refund_pending | 22610 | A refund action is initiated, but prior action is needed before the refund is applied (for example, the platform is waiting on a bank deposit or a batch processing). |
| refund_flagged | 22650 | The funds will be refunded to the funding source of the buyer, after manual review to approve the refund. |
| off_platform_refunded | 22670 | The funds have been refunded to the buyer through a means outside of the platform. |
| partial_completed | 22700 | Partial release of funds have been requested by the seller in the transaction. |
| partial_paid | 22800 | Partial release of funds have occurred in the transaction. |
| off_platform_chargedback | 22680 | The funds have been charged back by the buyer’s issuing bank through a means outside of the platform. |
Item Refund States
The following table lists the states that an item can undergo during a refund process. This is displayed, when applicable, under refund_state, in addition to the item state.
| Refund State | Code | Description |
|---|---|---|
| pending | 22600 | A refund has been initiated by the seller. |
| requested | 22620 | A refund has been requested by the buyer. |
| processing | 22622 | The refund has been triggered and is being processed. |
| pending_return | 22630 | The refund is awaiting the direct debit from the seller’s bank account. Once the funds are direct-debited, these will be returned to the item’s funding source. |
| pending_direct_credit | 22640 | The refund is being processed for direct credit to the buyer’s bank account. The item will be marked a success after 1 business day, if the funds do not bounce. |
| failed | 22660 | The refund attempt has failed due to an invalid funding source. This could be due to an expired card or insufficient funds. |
| success | 22690 | The refund has been successfully completed. |
Refund State Matrix
The following table provides shows both the item state and refund_state which an item undergoes during a refund process.
Full refund for a completed item
| Item State | Refund State | Description |
|---|---|---|
| refund_pending | pending_return | The refund is awaiting the direct debit from the seller’s bank account. Once the funds are direct-debited, these will be returned to the item’s funding source. |
| pending_direct_credit | The refund is being processed for direct credit to the buyer’s bank account. The item will be marked a success after 1 business day, if the funds do not bounce. | |
| completed | failed | The refund attempt has failed due to an invalid funding source. This could be due to an expired card or insufficient funds. |
| refunded | success | The refund has been successfully completed. |
Partial refund for a completed item
| State | Refund state | Description |
|---|---|---|
| refund_pending | pending_return | The refund is awaiting the direct debit from the seller’s bank account. Once the funds are direct-debited, these will be returned to the item’s funding source. |
| pending_direct_credit | The refund is being processed for direct credit to the buyer’s bank account. The item will be marked a success after 1 business day, if the funds do not bounce. | |
| completed | failed | The refund attempt has failed due to an invalid funding source. This could be due to an expired card or insufficient funds. |
| success | The refund has been successfully completed. |
Full refund for a non-completed item
| State | Refund state | Description |
|---|---|---|
| refund_pending | pending_return | The refund is awaiting the direct debit from the seller’s bank account. Once the funds are direct-debited, these will be returned to the item’s funding source. |
| pending_direct_credit | The refund is being processed for direct credit to the buyer’s bank account. The item will be marked a success after 1 business day, if the funds do not bounce. | |
| payment_deposited, payment_held, partial_paid, partial_completed, or work_completed | failed | The refund attempt has failed due to an invalid funding source. This could be due to an expired card or insufficient funds. |
| refunded | success | The refund has been successfully completed. |
Partial refund for a non-completed item
| State | Refund State | Description |
|---|---|---|
| refund_pending | pending_return | The refund is awaiting the direct debit from the seller’s bank account. Once the funds are direct-debited, these will be returned to the item’s funding source. |
| pending_direct_credit | The refund is being processed for direct credit to the buyer’s bank account. The item will be marked a success after 1 business day, if the funds do not bounce. | |
| payment_deposited, payment_held, partial_paid, partial_completed, or work_completed | failed | The refund attempt has failed due to an invalid funding source. This could be due to an expired card or insufficient funds. |
| success | The refund has been successfully completed. |
User States
The following table lists the states available that a user can assume on your platform.
| Status | Code | Description |
|---|---|---|
| pending | 23000 | Waiting for information of the user to fulfil our KYC data requirements. |
| pending_check | 23100 | Information received, waiting for Assembly to Approve the KYC. |
| approved_kyc_check | 23150 | Stage 1 of the KYC is approved. |
| approved | 23200 | Stage 1 and underwriting of the user has been approved. |
Batch Transaction Statuses
The below statuses are the available statuses for a Batch Transaction.
| State | Code | Description |
|---|---|---|
| successful | 12000 | The Batch Transaction has been processed successful, this means a direct debit has been received or a disbursement has been sent. |
| pending_successful | 12010 | The Batch Transaction has not bounced after 3 business days, but needs to be reviewed by our Payments Team before it is tagged successful. |
| batched | 12200 | The Batch Transaction has been created and is being processed by the batch process. This process runs twice a day. |
| invalid_account_details | 12360 | The Batch Transaction has failed due to incorrect bank account details. |
| failed_direct_debit | 12370 | The Batch Transaction has been dishonoured due to insufficient funds or other restrictions. Please refer user to contact their financial institution. |
| bank_processing | 12700 | The Batch Transaction has been imported to the bank and is being processed. |
| errored | 12900 | The Batch Transaction contained an error and will no longer be processed. |
Batch Transactions Matrix
Both item states and batch transactions statuses show where the item is in a payment workflow. Together, these two fields can tell you the flow of funds after an item has been paid for.
For direct debit payments (pay-ins)
| Item State | Batch Transaction Status | Description |
|---|---|---|
| payment_pending | pending | The direct debit payment has been triggered, but the payment hasn’t yet been included in a batch for processing. |
| batched | The payment has been included in a transaction batch, which is waiting to be processed. | |
| bank_processing | The payment, along with other payments in the same batch, is already being processed by the bank. | |
| payment_deposited | successful | The payment was successfully processed by the bank and the funds are now in the Assembly escrow vault. |
| pending | invalid_account_details | The payment wasn’t successful due to incorrect bank account details. |
| failed_direct_debit | The payment wasn’t honoured due to insufficient funds or other restrictions. |
For direct credit payments (pay-outs)
| Item State | Batch Transaction Status | Description |
|---|---|---|
| completed | pending | The direct credit payment has been triggered, but the payment hasn’t yet been included in a batch for processing. |
| batched | The payment has been included in a transaction batch, which is waiting to be processed. | |
| bank_processing | The payment, along with other payments in the same batch, is already being processed by the bank. | |
| successful | The payment was successfully processed by the bank and the funds have now been credited to the seller’s bank account. | |
| pending | invalid_account_details | The payment wasn’t successful due to incorrect bank details. |
Input formats
Bank account formats by country
When using the Create bank account API call, the following formats are required for each of the specified countries below. If a country you are trying to send or receive money from is not listed below, please let us know through Assembly support.
Australia
- Routing number = 6-digit Australian bank-state-branch (BSB) number
- Account number = bank account number
New Zealand
- Routing number = None
- Account number = Complete New Zealand bank code (consisting of the 6-digit New Zealand bank prefix + 7-digit bank account number + 2- or 3-digit account type)
United States
- Routing number = 9-digit US routing number
- Account number = bank account number
International payments
- Routing number = 8- to 11-character SWIFT code
- Account number = bank account number
If you have an Australian or New Zealand bank account and are trying to receive money from overseas, please contact Assembly support to assist you.
Error Codes
This section walks you through some of the most common error messages which you may encounter when using our API calls. Most error messages provide information on what caused an error, which can often guide you on resolving the issue. However, if you are unable to resolve an error, please contact Assembly support for further help and guidance.
HTTP status codes
The following table lists some common HTTP status codes which you may encounter when using our API calls. Refer to the information for guidance when you encounter an unfamiliar error.
| Status | Description |
|---|---|
| 200 OK | The request was successfully processed. |
| 201 Created | The request successfully created an entry (which could be a user, item, bank account, etc.) |
| 401 Unauthorized | The request could not be granted due to access restrictions. Contact Assembly support if you want to make changes to your platform, but are unable to. |
| 404 Not Found | The information requested was not found. Ensure that you have entered the correct details for your request. |
| 408 Request Timeout | The request took too long to be sent from your client to our servers. Please check your internet connection before you try again. Contact Assembly support if the issue does not seem to be with your internet connection. |
| 422 Unprocessable Entity | The request could not be processed because some fields require your input or correction. See the API response for guidance. |
| 500 Internal Server Error | An unexpected error was encountered. Contact Assembly support if this error persists. |
| 502 Bad Gateway | There is a problem communicating between servers. Please try again after a few minutes. |
| 503 Service Unavailable | Our servers are currently down or unable to process your request. See our Status page for updates. Contact Assembly support if this error persists. |
| 504 Gateway Timeout | The request took too long to be sent between servers. Please try again after a few minutes or see our Status page for updates. Contact Assembly support if this error persists. |
Payment-related errors
The following table lists common errors you may encounter when using the Make Payment, Authorize Payment, Refund, and other payment-related API calls.
| Error message | Description |
|---|---|
| Account must belong to the user | You’ve entered a bank or card account number that is not associated with the buyer. |
| Account ID: invalid format | You’ve entered a bank or card account number in a format that our system does not recognise. |
| Payment is already made for <item name> | You are trying to pay for an item that is already paid for. |
| Action is invalid, state transition invalid | You are trying to pay for an item that could already be fully paid for, be in a payment pending state, be in a payment held state due to suspected fraudulent activity, or have previously been refunded. |
| “id”: [“invalid”] | You’ve entered an incorrect item ID, or an invalid bank or card account number. |
| Credit card payment failed: Invalid billing descriptor | A credit card payment could not be processed due to how your platform is configured to display Soft Descriptors. This error may appear on US-based platforms. Contact Assembly support if this error persists. |
| Credit card payment failed: Do Not Honor | The credit card used for this transaction could have temporary or permanent restrictions placed on it by the issuing bank, have been blocked due to suspected fraudulent activity, or have insufficient funds. Please refer the buyer to their issuing bank. |
| Credit card payment failed: Refer to Card Issuer | The credit card used for this transaction is either expired or flagged as lost or stolen by the issuing bank. Please refer the buyer to their issuing bank. |
| Credit card authorization failed: Unable to communicate with the payment system | There is a problem communicating with the payment gateway used for this transaction. The transaction may be attempted again after a few minutes. |
| Credit card authorization failed: The payment gateway is currently unavailable. | The payment gateway used for this transaction is out of service or inaccessible at this time. The transaction may be attempted again after a few minutes. |
| Credit card authorization failed: Refer to card issuer | The credit card used for this transaction could have been blocked due to suspected fraudulent activity or be expired or flagged as lost or stolen by the issuing bank. Please refer the buyer back to their issuing bank. |
| Credit card authorization failed: Unable to process the purchase transaction | The credit card used to fund this transaction has been denied. Please refer the buyer to their issuing bank. |
| Credit card authorization failed: Transaction amount [YYYYY.YY] exceeded limit of [XXXXX.XX]. | The credit card transaction was declined due to a transaction limit imposed on the payment gateway. Contact Assembly support if you want to set or update the transaction limits for your platform. |
| Credit card refund failed: Stolen card, pick up | The credit card refund failed because the card was reported stolen. Please reach out to the cardholder and coordinate with Assembly to make the refund. |
| User currently held and not permitted to actively transact | The buyer’s account is currently held due to suspicious activity. See our guide on Fraud and Risk for more information. |
| You cannot pay via direct debit without authority | The buyer has not provided a direct debit authority associated with the bank account. |
| You cannot transact across different currencies | Your platform is not configured to support the currency in use. Contact Assembly support if you’d like to support more currencies on your platform. |
| You cannot pay by credit card for this transaction. | Your platform did not allow the credit card payment which could have been due to a payment restriction in place which limits or disallows credit card payments, or an underwriting threshold in place for the buyer. |
| You cannot pay by direct debit for this transaction. | Your platform did not allow the direct debit payment which could have been due to a payment restriction in place which limits or disallows direct debit payments, or an underwriting threshold in place for the buyer. |
| You cannot pay by digital wallet for this transaction. | Your platform did not allow the digital wallet payment which could have been due to a payment restriction in place which limits or disallows digital wallet payments, or an underwriting threshold in place for the buyer. |
| You cannot pay by wire transfer for this transaction. | Your platform did not allow the wire transfer payment which could have been due to a payment restriction in place which limits or disallows wire transfer payments, or an underwriting threshold in place for the buyer. |
| Error processing credit card. If this error persists, please contact our support team. | The credit card used to fund this transaction does not have enough available funds. |
| Action not available for items with completed state | Your platform is not configured to allow refunds for items that have been fully paid and delivered. Contact Assembly support if you would like to allow refunds for completed items on your platform. |
| Partial refunds are not allowed. | Your platform is not configured to allow partial refunds. Contact Assembly support if you would like to allow partial refunds on your platform. |
User account-related errors
The following table lists common errors you may encounter when using the Create User, Create Bank Account, Create Card Account, and other user account-related API calls.
| Error message | Description |
|---|---|
| “user”: [ “must have firstname, lastname, dob, email, government_number” | The information you’ve entered for creating a user is incomplete. Specific fields are required for KYC. See our Fraud and Risk Overview for more information. |
| “user_id”: [ “required field missing” | You are trying to create a bank or card account without a user associated with it. |