MENU
cURL Ruby .NET PHP

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
email 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

New Zealand

United States

International payments

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.

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.

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.