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.

Account Verifications

Account verifications are a class of calls associated with our instant verification feature.

There are two types of account verification:

Create Account Verification

Example request




curl -X "POST" "https://test.api.promisepay.com/account_verifications" \
  -H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
  -H "Content-Type: application/json" \
  -d "{\"verification_type\":\"online_banking\",\"user_id\":\"5830def0-ffe8-11e5-86aa-5e5517507c66\"}"

Example response (201)

{
    "account_verifications": {
        "id": "fcdce272-0369-444a-af38-980655b2fef8",
        "status": "not_verified",
        "user_session_token": "08312016_0:de845a44a568da64826ceedda95febd7dba16f9de0ed494c3e3d968ed3c1fec5d3e2c42578f47c60f3f07708b3876cca43c297149c6a70ec85807afd0995052d",
        "access_token": "1bedfb47fba12b1bef8fd7815e0b2d3930e6e6bd9f0c95e209bf385ab0aed8c4",
        "fastlink": "https://auyirestmasternode.stage.yodleeinteractive.com/authenticate/private-ausandbox10/?channelAppName=auyirestmaster",
        "app_id": "10003620",
        "callback_url": "https://test.api.promisepay.com/account_verifications/fcdce272-0369-444a-af38-980655b2fef8/confirm",
        "redirect": true,
        "links": {
            "self": "/account_verifications/fcdce272-0369-444a-af38-980655b2fef8",
            "bank_accounts": "/account_verifications/fcdce272-0369-444a-af38-980655b2fef8/bank_accounts"
        }
    }
}

Creates an account verification instance to be associated with either a user or an existing bank account

When instant verification is enabled, account verification instances are created automatically for all new bank accounts.

When you create an account verification instance, you can define its associated user_id or bank account_id, but not both.

Endpoint

POST /account_verifications

Parameter

Parameter Type Description
verification_type required string Method of verification to be used. Use online_banking for this field.
user_id required conditionally string user ID to be associated with the account verification; used exclusively for instant verification
account_id required conditionally string bank account ID to be associated with the account verification; can be used for penny verification or instant verification

Show Account Verification

Example request




curl -X "GET" "https://test.api.promisepay.com/account_verifications/fcdce272-0369-444a-af38-980655b2fef8" \
  -H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \

Example response (200)

{
    "account_verifications": {
        "id": "fcdce272-0369-444a-af38-980655b2fef8",
        "status": "not_verified",
        "user_session_token": "08312016_0:de845a44a568da64826ceedda95febd7dba16f9de0ed494c3e3d968ed3c1fec5d3e2c42578f47c60f3f07708b3876cca43c297149c6a70ec85807afd0995052d",
        "access_token": "1bedfb47fba12b1bef8fd7815e0b2d3930e6e6bd9f0c95e209bf385ab0aed8c4",
        "fastlink": "https://auyirestmasternode.stage.yodleeinteractive.com/authenticate/private-ausandbox10/?channelAppName=auyirestmaster",
        "app_id": "10003620",
        "callback_url": "https://test.api.promisepay.com/account_verifications/fcdce272-0369-444a-af38-980655b2fef8/confirm",
        "redirect": true,
        "links": {
            "self": "/account_verifications/fcdce272-0369-444a-af38-980655b2fef8",
            "bank_accounts": "/account_verifications/fcdce272-0369-444a-af38-980655b2fef8/bank_accounts"
        }
    }
}

Shows details of a specific account verification instance using a given :id

Endpoint

GET /account_verifications/:id

Parameters

Parameter Type Description
id required string Account verification :id

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",
      "companies": "7b85aa9c-fc54-4449-afef-f52fc2b94cd3",
      "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

Show Bank Account Instant Verification

Example request




curl -X "GET" "https://test.api.promisepay.com/bank_accounts/46deb476-c1a6-41eb-8eb7-26a695bbe5bc/instant_verification" \
    -H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="

Example response (200)

{
    "account_verifications": {
        "id": "fcdce272-0369-444a-af38-980655b2fef8",
        "status": "not_verified",
        "user_session_token": "08312016_0:de845a44a568da64826ceedda95febd7dba16f9de0ed494c3e3d968ed3c1fec5d3e2c42578f47c60f3f07708b3876cca43c297149c6a70ec85807afd0995052d",
        "access_token": "1bedfb47fba12b1bef8fd7815e0b2d3930e6e6bd9f0c95e209bf385ab0aed8c4",
        "fastlink": "https://auyirestmasternode.stage.yodleeinteractive.com/authenticate/private-ausandbox10/?channelAppName=auyirestmaster",
        "app_id": "10003620",
        "callback_url": "https://test.api.promisepay.com/account_verifications/fcdce272-0369-444a-af38-980655b2fef8/confirm",
        "redirect": true,
        "links": {
            "self": "/account_verifications/fcdce272-0369-444a-af38-980655b2fef8",
            "bank_accounts": "/account_verifications/fcdce272-0369-444a-af38-980655b2fef8/bank_accounts"
        }
    }
}

Shows the account instant verification instance associated with the bank account using a given :id

Endpoint

GET /bank_accounts/:id/instant_verification

Parameters

Parameter Type Description
id required 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",
       "invoice_url": "http://assemblypayments.com/sample-invoice.pdf",
    "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 Merchant/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.
invoice_url String Location of the custom Invoice

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 Merchant/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

List Item TDS Checks

Example Request




curl -X "GET" "https://test.api.promisepay.com/items/b8a15039-99ef-6bde-bdde-fde3664a3048/tds_checks" \
    -H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="

Example Response (200)

{
  "tds_checks": [
    {
      "id": "6a4bf33c-10aa-43ab-9b0e-9da849b413c9",
      "created_at": "2016-09-26T04:44:21.962Z",
      "updated_at": "2016-09-26T04:44:53.851Z",
      "state": "authorized",
      "bank_page_url": "js.prelive.promisepay.com/3ds.html?acs_url=https://0eafstag.cardinalcommerce.com/EAFService/jsp/v1/redirect&payload=P.502de2bca51fb81dba1fd7c5748b4f3641169ccb5cb39f45a9f12a4589dce6dd9b42f8bb9617f76441ca7a428aa59ad18e0c082dc1381acc757697a415b7221c0f2b6108b9a9723604f5b851513f5bea&term_url=https://secure-api.staging.promisepay.com/tds_checks/6a4bf33c-10aa-43ab-9b0e-9da849b413c9",
      "links": {
        "responses": "/tds_checks/6a4bf33c-10aa-43ab-9b0e-9da849b413c9/responses"
      }
    }
  ],
  "meta": {
    "limit": 10,
    "offset": 0,
    "total": 1
  },
  "links": {
    "self": "/items/b8a15039-99ef-6bde-bdde-fde3664a3048/tds_checks"
  }
}

Retrieves an ordered and paginated list of TDS checks associated with the item for 3-D Secure transactions

Endpoint

GET /items/:id/tds_checks

Parameters

Parameter Type Description
id string marketplace item ID

Show Item Funding Account

Example Request




curl -X "GET" "https://test.api.promisepay.com/items/b8a15039-99ef-6bde-bdde-fde3664a3048/funding_account" \
    -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": "/items/b8a15039-99ef-6bde-bdde-fde3664a3048/funding_account",
      "users": "/card_accounts/fa282b54-4728-4732-82e2-75bded33993e/users"
    }
  }
}

Show the Funding Account that paid for an Item using a given :id.

Endpoint

GET /items/:id/funding_account

Parameters

Parameter Type Description
id String 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

Claim Funds

Example request




curl -X "PATCH" "https://test.api.promisepay.com/items/100fd4a0-0538-11e6-b512-3e1d05defe78/claim_funds" \
    -H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="

Example response

{
  "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": "cancelled_fees_claimed",
    "net_amount": 0,
    "refunded_amount": 10000,
    "released_amount": 0,
    "buyer_fees": 0,
    "seller_fees": 0,
    "credit_card_fee": 200,
    "paypal_fee": 0,
    "seller_url": "",
    "buyer_url": "",
    "direct_debit_fee": 0,
    "status": 22676,
    "amount": 10000,
    "payment_type_id": 1,
    "due_date": "2016-04-28",
    "pending_release_amount": 0,
    "deposit_reference": "100014013962813",
    "promisepay_fee": 4,
    "total_outstanding": 200,
    "total_amount": 10200,
    "currency": "AUD",
    "payment_method": "credit card",
    "refund_message": "Refund after cancelled job",
    "refund_amount": 10000,
    "refund_state": "success",
    "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"
    }
  }
}

Refunds an item’s funds held in escrow while the platform retains the credit card fees associated with the transaction.

Note: This API call has to be enabled on your platform for it to work. Contact Assembly support if you would like this call to be in effect on your platform.

Endpoint

PATCH /items/:id/claim_funds

Parameters

Parameter Type Description
id string 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

Process Wire Transfer

Example request




curl -X "PATCH" "https://test.api.promisepay.com/items/100fd4a0-0538-11e6-b512-3e1d05defe78/process_wire" \
    -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.",
    "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"
    }
  }

Processes a pending wire transfer. Used for items in a wire_pending state.

Note: This API call is only available for processing wire transfers in pre-live.

Endpoint

PATCH /items/:id/process_wire

Parameters

Parameter Type Description
id string 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

Merchants

Merchants API allows for a complete Merchant to be created and maintained in Assembly. This will allow for a legal entity, company, settlement account, billing descriptor and merchant gateway to be set up that will allow for a merchant to accept several payment types.

A merchant can be created for an existing customer by specifying the customer ID, or for a new customer by specifying the customer details. There are a number of objects that are connected to a Merchant:

Customer: The customer that has been provisioned a merchant facility. They can be provisioned one or many merchant accounts.

Principal: The principal representative of the customer.

Principal Address: The principal representative’s address.

Company: The company of the customer.

Company Address: The company’s address of the customer.

Terminals: One or many terminals connected to the Merchant.

Configurations: One or many configurations that determine different operations and behaviours within the Merchant. This used to configure the API.

Create Merchant

Example Request

# Pending Ruby Example
# Pending PHP Example
# Pending .NET Example
# Pending cURL Example

Example Response (201)

{
   "merchants":{
      "id":"cb7eafc1-571c-425c-9adc-f56cb585cd68",
      "created_at":"2016-06-10T07:30:10.554Z",
      "updated_at":"2016-06-10T07:30:17.350Z",
      "status":"pending",
      "reference":"104998716",
      "billing_descriptor":"PRM*XYZPLUMBING",
      "master_merchant_id":"0129876",
      "merchant_id":"01234567",
      "type":"CNP",
      "category_code":"5515",
      "customer":{
        "id":"5830def0-ffe8-11e5-86aa-5e5517507c66",
        "created_at":"2016-06-10T07:30:10.554Z",
        "updated_at":"2016-06-10T07:30:17.350Z",
        "company":{
          "id":"20ad3445-18b8-48f4-8470-a7cfef7d44cf",
          "created_at":"2016-06-10T07:30:10.554Z",
          "updated_at":"2016-06-10T07:30:17.350Z",
          "legal_name":"XYZ Plumbing PTY LTD",
          "name":"XYZ Plumbing",
          "business_number":"123456789",
          "incorporation_date":"10/8/2008",
          "phone":"0390001234",
          "url":"https://michael.merchant.com",
          "type":"Sole Trader|Corporation",
          "timezone": "AEST",
          "address":{
            "created_at":"2016-06-10T07:30:10.554Z",
            "updated_at":"2016-06-10T07:30:17.350Z",
            "address_line1":"123 Test St",
            "address_line2":"",
            "city":"Sydney",
            "state":"NSW",
            "postcode":"2000",
            "country":"Australia"
          },
          "principal":{
            "id":"064d6800-fff3-11e5-86aa-5e5517507c66",
            "created_at":"2016-06-10T07:30:10.554Z",
            "updated_at":"2016-06-10T07:30:17.350Z",
            "first_name":"Michael",
            "last_name":"Merchant",
            "email":"michael@merchant.com",
            "mobile":"+61412341234",
            "date_of_birth":"12/04/1980",
                "timezone": "+1000",
                "government_number": "",
            "address": {
               "address_line1":"123 Test St",
               "address_line2":"",
               "city":"Sydney",
               "state":"NSW",
               "postcode":"2000",
               "country":"Australia"
            }
          }
        }  
      },
      "terminals":[
        {
          "id":"31cebb2c-b823-4843-b290-9737323c8781",
          "terminal_id":"1234444",
          "created_at":"2016-06-10T07:30:17.350Z",
          "provisioned_at":"2016-06-10T07:30:17.350Z",
          "terminal_name":"Van 23",
          "hardware_provider":"QUEST"
        },
        {
          "id":"2c07623a-e021-47cd-921c-c4954fd97116",
          "terminal_id":"1234445",
          "created_at":"2016-06-10T07:30:17.350Z",
          "provisioned_at":"2016-06-10T07:30:17.350Z",
          "terminal_name":"Office HQ",
          "hardware_provider":"QUEST"
        }
      ],
      "billing_account":{
        "active": true,
        "created_at": "2016-04-12T09:20:38.540Z",
        "updated_at": "2016-04-12T09:20:38.540Z",
        "id": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
        "currency": "AUD",
        "bank_account": {
          "bank_name": "Bank of Australia",
          "country": "AUS",
          "account_name": "Samuel Seller",
          "routing_number": "XXXXX3",
          "account_number": "XXX234",
          "holder_type": "personal",
          "account_type": "checking"
        },
      },
      "chargeback_account":{
        "active": true,
        "created_at": "2016-04-12T09:20:38.540Z",
        "updated_at": "2016-04-12T09:20:38.540Z",
        "id": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
        "currency": "AUD",
        "bank_account": {
          "bank_name": "Bank of Australia",
          "country": "AUS",
          "account_name": "Samuel Seller",
          "routing_number": "XXXXX3",
          "account_number": "XXX234",
          "holder_type": "personal",
          "account_type": "checking"
        },
      },  
      "settlement_account":{
        "active": true,
        "created_at": "2016-04-12T09:20:38.540Z",
        "updated_at": "2016-04-12T09:20:38.540Z",
        "id": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
        "currency": "AUD",
        "bank_account": {
          "bank_name": "Bank of Australia",
          "country": "AUS",
          "account_name": "Samuel Seller",
          "routing_number": "XXXXX3",
          "account_number": "XXX234",
          "holder_type": "personal",
          "account_type": "checking"
        },
      },
      "configurations":[
        {
          "configuration":"platform_kyc_processing",
          "enabled":true
        },
        {
          "configuration":"direct_settlement",
          "enabled":true
        },
        {
          "configuration":"settlement_frequency",
          "value":"daily"
        },
        {
          "configuration":"hold_for",
          "value":"2 days",
          "enabled":true
        },
        {
          "configuration":"branding",
          "value":{
            "logo_url": "",
            "color_1":"",
            "color_2":"",
            "color_3":"",
            "color_4":""
          },
          "enabled":true
        },
      ],   
      "links":{
         "self":"/merchants/cb7eafc1-571c-425c-9adc-f56cb585cd68",
         "payment_instructions":"/merchants/cb7eafc1-571c-425c-9adc-f56cb585cd67/payment_instructions"
      }
   }
}

Will accept full set of parameters to set up a merchant.

Endpoint

POST /merchants

Parameters

Parameter Type Required/Optional Description
MERCHANT
id string required Merchant Identifier (MID) eg. 01234567
category_code integer required Mercahnt category code (MCC) eg. 1234
status string required eg. Active, Existing, Pending, Suspended
billing_descriptor string required eg. PRM*Platform
type string required Card Not Present, Card Presenteg. CNP or CP
master_merchant_id string optional Master Merchant Identifier (MID) eg. 01234567
reference string optional Merchant reference (eg. Branch reference)
description string optional Merchant description (eg. CNP merchant account for Plumbing division of Handyman company)
CUSTOMER
customer.id string required Pass through an existing Customer or the details of a new Customer (see below). If only the ID is provided, a Customer will be assigned, if no ID is provided, we will use the Customer details below to create the Customer.
CUSTOMER PRINCIPAL required
customer.principal.email string required Unique to platform.
customer.principal.first_name string required
customer.principal.last_name string optional
customer.principal.mobile string required International number format. Include ’+’ and no spaces.
customer.principal.dob date optional Date of birth. e.g. DD/MM/YYYY
customer.principal.government_number string optional ABN or TFN (optional). Not required if Company.
customer.principal.timezone string optional ISO 8601 format. E.g. ’+1000’
CUSTOMER PRINCIPAL ADDRESS required
customer.principal.address.address_line1 string required
customer.principal.address.address_line2 string optional
customer.principal.address.city string required
customer.principal.address.state string required
customer.principal.address.postcode string required
customer.principal.address.country string required Country (ISO 3 character code).
CUSTOMER COMPANY optional Required if the Merchant is a Company. If provided, parameters below must be supplied.
customer.company.legal_name string required
customer.company.name string required
customer.company.type string required
customer.company.incorporation_date date required
customer.company.phone string required
customer.company.url string optional
customer.company.business_number string required ABN or ACN
customer.company.timezone string optional ISO 8601 format. E.g. ’+1000’
CUSTOMER COMPANY ADDRESS optional Required if the Merchant is a Company. If provided, parameters below must be supplied.
customer.company.address.address_line1 string required
customer.company.address.address_line2 string optional
customer.company.address.city string required
customer.company.address.state string required
customer.company.address.postcode string required
customer.company.address.country string required
SETTLEMENT ACCOUNT required
settlement_account.bank_name string required
settlement_account.name string required
settlement_account.bsb string required
settlement_account.account_number string required
settlement_account.currency string required
BILLING ACCOUNT optional This is optional, if provided, parameters below must be supplied.
billing_account.bank_name string optional
billing_account.name string optional
billing_account.bsb string optional
billing_account.account_number string optional
billing_account.currency string optional
CHARGEBACK ACCOUNT optional This is optional, if provided, parameters below must be supplied.
chargeback_account.bank_name string optional
chargeback_account.name string optional
chargeback_account.bsb string optional
chargeback_account.account_number string optional
chargeback_account.currency string optional
TERMINALS optional These are optional, if provided, parameters below must be supplied.
terminals[0].id string required
terminals[0].hardware_provider string required
terminals[0].name string required
terminals[0].provisioned_at date required
CONFIGURATIONS optional These are optional, if provided, parameters below must be supplied.
configurations[0].name string required
configurations[0].enabled boolean required
configurations[0].value string optional Dependent on the configuration.

List Merchants

Example Request





Example Response (200)

{
  "merchants": [
   {
      "id":"cb7eafc1-571c-425c-9adc-f56cb585cd68",
      "created_at":"2016-06-10T07:30:10.554Z",
      "updated_at":"2016-06-10T07:30:17.350Z",
      "status":"pending",
      "reference":"104998716",
      "billing_descriptor":"PRM*XYZPLUMBING",
      "master_merchant_id":"0129876",
      "merchant_id":"01234567",
      "type":"CNP",
      "category_code":"5515",
      "customer":{
        "id":"5830def0-ffe8-11e5-86aa-5e5517507c66",
        "created_at":"2016-06-10T07:30:10.554Z",
        "updated_at":"2016-06-10T07:30:17.350Z",
        "company":{
          "id":"20ad3445-18b8-48f4-8470-a7cfef7d44cf",
          "created_at":"2016-06-10T07:30:10.554Z",
          "updated_at":"2016-06-10T07:30:17.350Z",
          "legal_name":"XYZ Plumbing PTY LTD",
          "name":"XYZ Plumbing",
          "business_number":"123456789",
          "incorporation_date":"10/8/2008",
          "phone":"0390001234",
          "url":"https://michael.merchant.com",
          "type":"Sole Trader|Corporation",
          "timezone": "AEST",
          "address":{
            "created_at":"2016-06-10T07:30:10.554Z",
            "updated_at":"2016-06-10T07:30:17.350Z",
            "address_line1":"123 Test St",
            "address_line2":"",
            "city":"Sydney",
            "state":"NSW",
            "postcode":"2000",
            "country":"Australia"
          },
          "principal":{
            "id":"064d6800-fff3-11e5-86aa-5e5517507c66",
            "created_at":"2016-06-10T07:30:10.554Z",
            "updated_at":"2016-06-10T07:30:17.350Z",
            "first_name":"Michael",
            "last_name":"Merchant",
            "email":"michael@merchant.com",
            "mobile":"+61412341234",
            "date_of_birth":"12/04/1980",
                "timezone": "+1000",
                "government_number": "",
            "address": {
               "address_line1":"123 Test St",
               "address_line2":"",
               "city":"Sydney",
               "state":"NSW",
               "postcode":"2000",
               "country":"Australia"
            }
          }
        }  
      },
      "terminals":[
        {
          "id":"31cebb2c-b823-4843-b290-9737323c8781",
          "terminal_id":"1234444",
          "created_at":"2016-06-10T07:30:17.350Z",
          "provisioned_at":"2016-06-10T07:30:17.350Z",
          "terminal_name":"Van 23",
          "hardware_provider":"QUEST"
        },
        {
          "id":"2c07623a-e021-47cd-921c-c4954fd97116",
          "terminal_id":"1234445",
          "created_at":"2016-06-10T07:30:17.350Z",
          "provisioned_at":"2016-06-10T07:30:17.350Z",
          "terminal_name":"Office HQ",
          "hardware_provider":"QUEST"
        }
      ],
      "billing_account":{
        "active": true,
        "created_at": "2016-04-12T09:20:38.540Z",
        "updated_at": "2016-04-12T09:20:38.540Z",
        "id": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
        "currency": "AUD",
        "bank_account": {
          "bank_name": "Bank of Australia",
          "country": "AUS",
          "account_name": "Samuel Seller",
          "routing_number": "XXXXX3",
          "account_number": "XXX234",
          "holder_type": "personal",
          "account_type": "checking"
        },
      },
      "chargeback_account":{
        "active": true,
        "created_at": "2016-04-12T09:20:38.540Z",
        "updated_at": "2016-04-12T09:20:38.540Z",
        "id": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
        "currency": "AUD",
        "bank_account": {
          "bank_name": "Bank of Australia",
          "country": "AUS",
          "account_name": "Samuel Seller",
          "routing_number": "XXXXX3",
          "account_number": "XXX234",
          "holder_type": "personal",
          "account_type": "checking"
        },
      },  
      "settlement_account":{
        "active": true,
        "created_at": "2016-04-12T09:20:38.540Z",
        "updated_at": "2016-04-12T09:20:38.540Z",
        "id": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
        "currency": "AUD",
        "bank_account": {
          "bank_name": "Bank of Australia",
          "country": "AUS",
          "account_name": "Samuel Seller",
          "routing_number": "XXXXX3",
          "account_number": "XXX234",
          "holder_type": "personal",
          "account_type": "checking"
        },
      },
      "configurations":[
        {
          "configuration":"platform_kyc_processing",
          "enabled":true
        },
        {
          "configuration":"direct_settlement",
          "enabled":true
        },
        {
          "configuration":"settlement_frequency",
          "value":"daily"
        },
        {
          "configuration":"hold_for",
          "value":"2 days",
          "enabled":true
        },
        {
          "configuration":"branding",
          "value":{
            "logo_url": "",
            "color_1":"",
            "color_2":"",
            "color_3":"",
            "color_4":""
          },
          "enabled":true
        },
      ],   
      "links":{
         "self":"/merchants/cb7eafc1-571c-425c-9adc-f56cb585cd68",
         "payment_instructions":"/merchants/cb7eafc1-571c-425c-9adc-f56cb585cd67/payment_instructions"
      }
   }],
  "links": {
    "self": "/merchants"
  },
  "meta": {
    "limit": 10,
    "offset": 0,
    "total": 1
  }
}

Retrieve an ordered and paginated list of existing Merchants.

Endpoint

GET /merchants

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 Merchant

Example Request





Example Response (200)

{
   "merchants":{
      "id":"cb7eafc1-571c-425c-9adc-f56cb585cd68",
      "created_at":"2016-06-10T07:30:10.554Z",
      "updated_at":"2016-06-10T07:30:17.350Z",
      "status":"pending",
      "reference":"104998716",
      "billing_descriptor":"PRM*XYZPLUMBING",
      "master_merchant_id":"0129876",
      "merchant_id":"01234567",
      "type":"CNP",
      "category_code":"5515",
      "customer":{
        "id":"5830def0-ffe8-11e5-86aa-5e5517507c66",
        "created_at":"2016-06-10T07:30:10.554Z",
        "updated_at":"2016-06-10T07:30:17.350Z",
        "company":{
          "id":"20ad3445-18b8-48f4-8470-a7cfef7d44cf",
          "created_at":"2016-06-10T07:30:10.554Z",
          "updated_at":"2016-06-10T07:30:17.350Z",
          "legal_name":"XYZ Plumbing PTY LTD",
          "name":"XYZ Plumbing",
          "business_number":"123456789",
          "incorporation_date":"10/8/2008",
          "phone":"0390001234",
          "url":"https://michael.merchant.com",
          "type":"Sole Trader|Corporation",
          "timezone": "AEST",
          "address":{
            "created_at":"2016-06-10T07:30:10.554Z",
            "updated_at":"2016-06-10T07:30:17.350Z",
            "address_line1":"123 Test St",
            "address_line2":"",
            "city":"Sydney",
            "state":"NSW",
            "postcode":"2000",
            "country":"Australia"
          },
          "principal":{
            "id":"064d6800-fff3-11e5-86aa-5e5517507c66",
            "created_at":"2016-06-10T07:30:10.554Z",
            "updated_at":"2016-06-10T07:30:17.350Z",
            "first_name":"Michael",
            "last_name":"Merchant",
            "email":"michael@merchant.com",
            "mobile":"+61412341234",
            "date_of_birth":"12/04/1980",
                "timezone": "+1000",
                "government_number": "",
            "address": {
               "address_line1":"123 Test St",
               "address_line2":"",
               "city":"Sydney",
               "state":"NSW",
               "postcode":"2000",
               "country":"Australia"
            }
          }
        }  
      },
      "terminals":[
        {
          "id":"31cebb2c-b823-4843-b290-9737323c8781",
          "terminal_id":"1234444",
          "created_at":"2016-06-10T07:30:17.350Z",
          "provisioned_at":"2016-06-10T07:30:17.350Z",
          "terminal_name":"Van 23",
          "hardware_provider":"QUEST"
        },
        {
          "id":"2c07623a-e021-47cd-921c-c4954fd97116",
          "terminal_id":"1234445",
          "created_at":"2016-06-10T07:30:17.350Z",
          "provisioned_at":"2016-06-10T07:30:17.350Z",
          "terminal_name":"Office HQ",
          "hardware_provider":"QUEST"
        }
      ],
      "billing_account":{
        "active": true,
        "created_at": "2016-04-12T09:20:38.540Z",
        "updated_at": "2016-04-12T09:20:38.540Z",
        "id": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
        "currency": "AUD",
        "bank_account": {
          "bank_name": "Bank of Australia",
          "country": "AUS",
          "account_name": "Samuel Seller",
          "routing_number": "XXXXX3",
          "account_number": "XXX234",
          "holder_type": "personal",
          "account_type": "checking"
        },
      },
      "chargeback_account":{
        "active": true,
        "created_at": "2016-04-12T09:20:38.540Z",
        "updated_at": "2016-04-12T09:20:38.540Z",
        "id": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
        "currency": "AUD",
        "bank_account": {
          "bank_name": "Bank of Australia",
          "country": "AUS",
          "account_name": "Samuel Seller",
          "routing_number": "XXXXX3",
          "account_number": "XXX234",
          "holder_type": "personal",
          "account_type": "checking"
        },
      },  
      "settlement_account":{
        "active": true,
        "created_at": "2016-04-12T09:20:38.540Z",
        "updated_at": "2016-04-12T09:20:38.540Z",
        "id": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
        "currency": "AUD",
        "bank_account": {
          "bank_name": "Bank of Australia",
          "country": "AUS",
          "account_name": "Samuel Seller",
          "routing_number": "XXXXX3",
          "account_number": "XXX234",
          "holder_type": "personal",
          "account_type": "checking"
        },
      },
      "configurations":[
        {
          "configuration":"platform_kyc_processing",
          "enabled":true
        },
        {
          "configuration":"direct_settlement",
          "enabled":true
        },
        {
          "configuration":"settlement_frequency",
          "value":"daily"
        },
        {
          "configuration":"hold_for",
          "value":"2 days",
          "enabled":true
        },
        {
          "configuration":"branding",
          "value":{
            "logo_url": "",
            "color_1":"",
            "color_2":"",
            "color_3":"",
            "color_4":""
          },
          "enabled":true
        },
      ],   
      "links":{
         "self":"/merchants/cb7eafc1-571c-425c-9adc-f56cb585cd68",
         "payment_instructions":"/merchants/cb7eafc1-571c-425c-9adc-f56cb585cd67/payment_instructions"
      }
   }
}

Show details of a specific Merchant using a given :id.

Endpoint

GET /merchants/:id

Parameters

Parameter Type Description
id String Merchant ID

Update Merchant

Example Request





Example Response (200)

{
   "merchants":{
      "id":"cb7eafc1-571c-425c-9adc-f56cb585cd68",
      "created_at":"2016-06-10T07:30:10.554Z",
      "updated_at":"2016-06-10T07:30:17.350Z",
      "status":"pending",
      "reference":"104998716",
      "billing_descriptor":"PRM*XYZPLUMBING",
      "master_merchant_id":"0129876",
      "merchant_id":"01234567",
      "type":"CNP",
      "category_code":"5515",
      "customer":{
        "id":"5830def0-ffe8-11e5-86aa-5e5517507c66",
        "created_at":"2016-06-10T07:30:10.554Z",
        "updated_at":"2016-06-10T07:30:17.350Z",
        "company":{
          "id":"20ad3445-18b8-48f4-8470-a7cfef7d44cf",
          "created_at":"2016-06-10T07:30:10.554Z",
          "updated_at":"2016-06-10T07:30:17.350Z",
          "legal_name":"XYZ Plumbing PTY LTD",
          "name":"XYZ Plumbing",
          "business_number":"123456789",
          "incorporation_date":"10/8/2008",
          "phone":"0390001234",
          "url":"https://michael.merchant.com",
          "type":"Sole Trader|Corporation",
          "timezone": "AEST",
          "address":{
            "created_at":"2016-06-10T07:30:10.554Z",
            "updated_at":"2016-06-10T07:30:17.350Z",
            "address_line1":"123 Test St",
            "address_line2":"",
            "city":"Sydney",
            "state":"NSW",
            "postcode":"2000",
            "country":"Australia"
          },
          "principal":{
            "id":"064d6800-fff3-11e5-86aa-5e5517507c66",
            "created_at":"2016-06-10T07:30:10.554Z",
            "updated_at":"2016-06-10T07:30:17.350Z",
            "first_name":"Michael",
            "last_name":"Merchant",
            "email":"michael@merchant.com",
            "mobile":"+61412341234",
            "date_of_birth":"12/04/1980",
                "timezone": "+1000",
                "government_number": "",
            "address": {
               "address_line1":"123 Test St",
               "address_line2":"",
               "city":"Sydney",
               "state":"NSW",
               "postcode":"2000",
               "country":"Australia"
            }
          }
        }  
      },
      "terminals":[
        {
          "id":"31cebb2c-b823-4843-b290-9737323c8781",
          "terminal_id":"1234444",
          "created_at":"2016-06-10T07:30:17.350Z",
          "provisioned_at":"2016-06-10T07:30:17.350Z",
          "terminal_name":"Van 23",
          "hardware_provider":"QUEST"
        },
        {
          "id":"2c07623a-e021-47cd-921c-c4954fd97116",
          "terminal_id":"1234445",
          "created_at":"2016-06-10T07:30:17.350Z",
          "provisioned_at":"2016-06-10T07:30:17.350Z",
          "terminal_name":"Office HQ",
          "hardware_provider":"QUEST"
        }
      ],
      "billing_account":{
        "active": true,
        "created_at": "2016-04-12T09:20:38.540Z",
        "updated_at": "2016-04-12T09:20:38.540Z",
        "id": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
        "currency": "AUD",
        "bank_account": {
          "bank_name": "Bank of Australia",
          "country": "AUS",
          "account_name": "Samuel Seller",
          "routing_number": "XXXXX3",
          "account_number": "XXX234",
          "holder_type": "personal",
          "account_type": "checking"
        },
      },
      "chargeback_account":{
        "active": true,
        "created_at": "2016-04-12T09:20:38.540Z",
        "updated_at": "2016-04-12T09:20:38.540Z",
        "id": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
        "currency": "AUD",
        "bank_account": {
          "bank_name": "Bank of Australia",
          "country": "AUS",
          "account_name": "Samuel Seller",
          "routing_number": "XXXXX3",
          "account_number": "XXX234",
          "holder_type": "personal",
          "account_type": "checking"
        },
      },  
      "settlement_account":{
        "active": true,
        "created_at": "2016-04-12T09:20:38.540Z",
        "updated_at": "2016-04-12T09:20:38.540Z",
        "id": "46deb476-c1a6-41eb-8eb7-26a695bbe5bc",
        "currency": "AUD",
        "bank_account": {
          "bank_name": "Bank of Australia",
          "country": "AUS",
          "account_name": "Samuel Seller",
          "routing_number": "XXXXX3",
          "account_number": "XXX234",
          "holder_type": "personal",
          "account_type": "checking"
        },
      },
      "configurations":[
        {
          "configuration":"platform_kyc_processing",
          "enabled":true
        },
        {
          "configuration":"direct_settlement",
          "enabled":true
        },
        {
          "configuration":"settlement_frequency",
          "value":"daily"
        },
        {
          "configuration":"hold_for",
          "value":"2 days",
          "enabled":true
        },
        {
          "configuration":"branding",
          "value":{
            "logo_url": "",
            "color_1":"",
            "color_2":"",
            "color_3":"",
            "color_4":""
          },
          "enabled":true
        },
      ],   
      "links":{
         "self":"/merchants/cb7eafc1-571c-425c-9adc-f56cb585cd68",
         "payment_instructions":"/merchants/cb7eafc1-571c-425c-9adc-f56cb585cd67/payment_instructions"
      }
   }
}

Update an existing Merchants attributes using a given :id.

Endpoint

PATCH /merchants/:id

Parameters

Parameter Type Required/Optional Description
MERCHANT
category_code integer required Mercahnt category code (MCC) eg. 1234
status string required eg. Active, Existing, Pending, Suspended
billing_descriptor string required eg. PRM*Platform
type string required Card Not Present, Card Presenteg. CNP or CP
master_merchant_id string optional Master Merchant Identifier (MID) eg. 01234567
reference string optional Merchant reference (eg. Branch reference)
description string optional Merchant description (eg. CNP merchant account for Plumbing division of Handyman company)
CUSTOMER
customer.id string required Pass through an existing Customer or the details of a new Customer (see below). If only the ID is provided, a Customer will be assigned, if no ID is provided, we will use the Customer details below to create the Customer.
CUSTOMER PRINCIPAL required
customer.principal.email string required Unique to platform.
customer.principal.first_name string required
customer.principal.last_name string optional
customer.principal.mobile string required International number format. Include ’+’ and no spaces.
customer.principal.dob date optional Date of birth. e.g. DD/MM/YYYY
customer.principal.government_number string optional ABN or TFN (optional). Not required if Company.
customer.principal.timezone string optional ISO 8601 format. E.g. ’+1000’
CUSTOMER PRINCIPAL ADDRESS required
customer.principal.address.address_line1 string required
customer.principal.address.address_line2 string optional
customer.principal.address.city string required
customer.principal.address.state string required
customer.principal.address.postcode string required
customer.principal.address.country string required Country (ISO 3 character code).
CUSTOMER COMPANY optional Required if the Merchant is a Company. If provided, parameters below must be supplied.
customer.company.legal_name string required
customer.company.name string required
customer.company.type string required
customer.company.incorporation_date date required
customer.company.phone string required
customer.company.url string optional
customer.company.business_number string required ABN or ACN
customer.company.timezone string optional ISO 8601 format. E.g. ’+1000’
CUSTOMER COMPANY ADDRESS optional Required if the Merchant is a Company. If provided, parameters below must be supplied.
customer.company.address.address_line1 string required
customer.company.address.address_line2 string optional
customer.company.address.city string required
customer.company.address.state string required
customer.company.address.postcode string required
customer.company.address.country string required
SETTLEMENT ACCOUNT required
settlement_account.bank_name string required
settlement_account.name string required
settlement_account.bsb string required
settlement_account.account_number string required
settlement_account.currency string required
BILLING ACCOUNT optional This is optional, if provided, parameters below must be supplied.
billing_account.bank_name string optional
billing_account.name string optional
billing_account.bsb string optional
billing_account.account_number string optional
billing_account.currency string optional
CHARGEBACK ACCOUNT optional This is optional, if provided, parameters below must be supplied.
chargeback_account.bank_name string optional
chargeback_account.name string optional
chargeback_account.bsb string optional
chargeback_account.account_number string optional
chargeback_account.currency string optional
TERMINALS optional These are optional, if provided, parameters below must be supplied.
terminals[0].id string required
terminals[0].hardware_provider string required
terminals[0].name string required
terminals[0].provisioned_at date required
CONFIGURATIONS optional These are optional, if provided, parameters below must be supplied.
configurations[0].name string required
configurations[0].enabled boolean required
configurations[0].value string optional Dependent on the configuration.

Show Merchant Bank Account

Example Request





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"
    }
  }
}

Show the Merchant’s Bank Account using a given :id.

Endpoint

GET /merchants/:id/bank_accounts

Parameters

Parameter Type Description
id String Merchant ID

Show Merchant Wallet Account

Example Request





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": "/merchants/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 Merchant’s Wallet Account using a given :id.

Endpoint

GET /merchants/:id/wallet_accounts

Parameters

Parameter Type Description
id String Merchant ID

List Merchant Items

Example Request





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 Merchant is associated with using a given :id.

Endpoint

GET /merchants/:id/items

Parameters

Parameter Type Description
id String Merchant ID

SMS Reminders

When Approve SMS reminders are enabled on a platform, you can set when and how often these messages are sent out.

When you create an SMS reminder, this changes a configuration on your platform, an example of which can be seen on the right.

Prescribed format

{
  "marketplace_id": "00d8bade-a864-4b9d-9e0d-98b89b3861dd",
  "config" : {
    "payment_due_today_reminder" : true,
    "payment_due_reminders" : {
      "frequency" : 7,
      "offsets" : [4, 2, 1]
    },
    "payment_overdue_reminders" : {
      "frequency" : nil,
      "offsets" : [1, 2, 3, 4, 5, 6, 7],
      "final_date_offset" : nil
    }
  }
}

This example shows the default setting for all platforms.

The frequency field dictates the number of days between reminders. For example, if the frequency for the payment_due_reminders is 7, then a reminder will be sent in multiples of seven days prior to the due date (21 days prior, 14 days prior, 7 days prior, etc.), until the day the item’s payment is due. Alternatively, the frequency for the payment_overdue_reminder dictates that a reminder will be sent in multiples of days after the due date.

The final_date_offset is used in conjunction with frequency for payment_overdue_reminders. The final_date_offset dictates that reminders should stop a number of days after the due date. For example, if the final_date_offset is 3 and the the frequency is 1, then overdue reminders will be sent daily and will stop three days past the due date.

The offsets field dictates specific days from the due date when a reminder is sent. For example, if the offsets for the payment_due_reminders are 4, 2, and 1, then a reminder will be sent four days, two days, and a day before an item’s due date, respectively. Alternatively, the offsets for the payment_overdue_reminders dictates that a reminder will be sent on specific days after an item’s due date.

The offsets field has no relationship or interaction with the frequency and final_date_offset fields. You simply have the option to define the reminder schedule in terms of frequency, offsets, or a combination of both.

In addition, the frequency, offsets, and final_date_offset fields will not cause an overlap in the SMS reminders schedule. These fields can appear to cause duplicate SMS reminders to be sent. Nonetheless, our system accounts for these instances and will send at most one reminder on a given day.

Due dates are set on a item level when you Create an Item.

Create SMS Reminder

Example request




curl -X "POST" "https://test.api.promisepay.com/sms_reminders" \
  -H "Authorization: d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
  -H "Content-Type: application/json" \
  -d "{
  "marketplace_id": "00d8bade-a864-4b9d-9e0d-98b89b3861dd",
  "config" : {
    "payment_due_today_reminder" : true,
    "payment_due_reminders" : {
      "frequency" : 1,
      "offsets" : [1,2]
    },
    "payment_overdue_reminders" : {
      "frequency" : 1,
      "offsets" : [1,2],
      "final_date_offset" : 1
    }
  }
}"

Example response (200)

{
  "id": 1093,
  "config": {
    "payment_due_today_reminder": true,
    "payment_due_reminders": {
      "frequency": 1,
      "offsets": [
        1,
        2
      ]
    },
    "payment_overdue_reminders": {
      "frequency": 1,
      "offsets": [
        1,
        2
      ],
      "final_date_offset": 1
    }
  }
}

Creates a custom schedule for your SMS reminders

Endpoint

POST /sms_reminders

Parameters

Parameter Type Description
marketplace_id string Your platform ID. Use the format prescribed above on the body of the request.
config string The configuration for your preferred SMS reminder schedule. Input the values on the body of the request, following the format prescribed above.

Show SMS Reminder

Example request




curl -X "GET" "https://test.api.promisepay.com/sms_reminders/1093" \
  -H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \

Example response (200)

{
  "id": 1093,
  "config": {
    "payment_due_today_reminder": true,
    "payment_due_reminders": {
      "frequency": 1,
      "offsets": [
        1,
        2
      ]
    },
    "payment_overdue_reminders": {
      "frequency": 1,
      "offsets": [
        1,
        2
      ],
      "final_date_offset": 1
    }
  }
}

Shows details of a specific SMS reminder schedule using a given :id

Endpoint

GET /sms_reminders/:id

Parameters

Parameter Type Description
id string SMS reminder ID

Update SMS Reminder

Example request




curl -X "PATCH" "https://test.api.promisepay.com/sms_reminders/1093?enabled=false" \
  -H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0=" \
  -H "content-type: application/json" \
  -d "{
  "marketplace_id": "00d8bade-a864-4b9d-9e0d-98b89b3861dd",
  "config" : {
    "payment_due_today_reminder" : true,
    "payment_due_reminders" : {
      "frequency" : 3,
      "offsets" : [1,2,3,4]
    },
    "payment_overdue_reminders" : {
      "frequency" : 3,
      "offsets" : [3,4],
      "final_date_offset" : 2
    }
  }
}"

Example response (200)

{
  "id": 1093,
  "config": {
    "payment_due_today_reminder": true,
    "payment_due_reminders": {
      "frequency": 3,
      "offsets": [
        1,
        2,
        3,
        4
      ]
    },
    "payment_overdue_reminders": {
      "frequency": 3,
      "offsets": [
        3,
        4
      ],
      "final_date_offset": 2
    }
  }
}

Updates an existing SMS reminder schedule using a given :id

Endpoint

PATCH /sms_reminders/:id

Parameters

Parameter Type Description
id string SMS reminder ID
config string The configuration for your preferred SMS reminder schedule. Input the values on the body of the request, following the format prescribed above.
enabled Boolean Toggle whether a given SMS reminder config is in effect

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

TDS Checks

TDS (3-D Secure) checks account for the information passed between the Assembly service and our merchant providers concerning the transaction state of an item that is undergoing 3-D Secure authentication.

Show TDS Check

Example Request




curl -X "GET" "https://test.api.promisepay.com/tds_checks/6a4bf33c-10aa-43ab-9b0e-9da849b413c9" \
    -H "Authorization: Basic d2Fsa3Rocm91Z2hAcHJvbWlzZXBheS5jb206T0dRNE56ZzNPVGM0TW1FMlpUSmpa REZtWkRWaVpqVTROR1ptTURFelpqYz0="

Example Response (200)

{
  "tds_checks": {
    "id": "6a4bf33c-10aa-43ab-9b0e-9da849b413c9",
    "created_at": "2016-09-26T04:44:21.962Z",
    "updated_at": "2016-09-26T04:44:53.851Z",
    "state": "authorized",
    "bank_page_url": "js.prelive.promisepay.com/3ds.html?acs_url=https://0eafstag.cardinalcommerce.com/EAFService/jsp/v1/redirect&payload=P.502de2bca51fb81dba1fd7c5748b4f3641169ccb5cb39f45a9f12a4589dce6dd9b42f8bb9617f76441ca7a428aa59ad18e0c082dc1381acc757697a415b7221c0f2b6108b9a9723604f5b851513f5bea&term_url=https://secure-api.staging.promisepay.com/tds_checks/6a4bf33c-10aa-43ab-9b0e-9da849b413c9",
    "links": {
      "self": "/tds_checks/6a4bf33c-10aa-43ab-9b0e-9da849b413c9",
      "responses": "/tds_checks/6a4bf33c-10aa-43ab-9b0e-9da849b413c9/responses"
    }
  }
}

Shows the details of a specific TDS check using a given :id

Endpoint

GET /tds_checks/:id

Parameters

Parameter Type Description
id string TDS check 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.

TDS State Matrix

The following table lists the states associated with an item undergoing a 3-D Secure transaction. These states accompany item states to indicate the status of a transaction.

Item State TDS State Description
payment_pending enrolled The card used for the transaction is verified to be enrolled in 3-D Secure. This will transition one of the authentication states.
not_enrolled The card used for the transaction is not enrolled in 3-D Secure and does not permit 3-D Secure transactions. Transaction cannot proceed. Contact your issuing bank or use another card from a different card scheme.
bypassed The 3-D Secure authentication is bypassed due to settings placed on the platform. This will transition to one of the authentication states.
lookup_not_available We cannot verify whether the card is enrolled in 3-D Secure at the time of request. Transaction cannot proceed. Contact Assembly support if this issue persists.
lookup_timeout We cannot verify whether the card is enrolled in 3-D Secure at the time of request. Transaction cannot proceed. Contact Assembly support if this issue persists.
lookup_error We cannot verify whether the card is enrolled in 3-D Secure at the time of request. Transaction cannot proceed. Contact Assembly support if this issue persists.
authenticate_not_available The card used for the transaction could not be authenticated with 3-D Secure at the time of request. Transaction cannot proceed. Contact Assembly support if this issue persists.
authenticate_error The card used for the transaction could not be authenticated with 3-D Secure. Transaction cannot proceed. Contact Assembly support if this issue persists.
authenticate_timeout The user failed to authenticate the 3-D Secure transaction in a timely manner. Transaction cannot proceed. Contact Assembly support to resolve this issue.
payment_deposited not_enrolled The transaction was processed successfully without 3-D Secure authentication. Payment has been successfully received in our escrow vault.
authorized The transaction was processed successfully with 3-D Secure authentication. Payment has been successfully received in our escrow vault.
completed not_enrolled The transaction was processed successfully without 3-D Secure authentication. The item is completed and the funds have been released.
authorized The transaction was processed successfully with 3-D Secure authentication. The item is completed and the funds have been released.
fraud_hold not_authorized The user failed to authenticate the 3-D Secure transaction. Payment is acknowledged as fraud and these funds will attempt to be refunded.

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