MSTS Seller Integration Documentation (Document Version - 2.0.27)

Document Change History

VERSIONCHANGE HISTORY
1.0.0Initial Version.
2.0.0Add currency attribute to the preauthorization and charge API.
2.0.1Add po_number attribute to the preauthorization API and the error codes for po_number validation.
2.0.2Support additional currencies for buyer application.
2.0.3Fix the link to buyer_application.
2.0.4Add a new endpoint for partial return.
Add a new attribute in buyer_application to pass the URL to link to ecommerce site.
Add a new attribute in buyer_application to specify the current charge amount in the shopping cart.
Support update of preauthorization amount
2.0.5Change buyer_application required parameter from buyer_reference_id to client_reference_id.
2.0.6Fix the description for reponse 400
2.0.7Add the new buyer payment term 'End of Month - Net 45'
2.0.8Add a new error code 400 - invalid_input
2.0.9Enhance API Doc, add more descriptions
2.0.10Modify charge endpoints to support discount_amount
2.0.11Add a new error code 405 - method_not_allowed
2.0.12Add shipping_tax_amount to Charge and Return
2.0.13Add shipping_discount_amount to Charge and Return
2.0.14Change url to app.msts.credit
2.0.15Add a new error code 400 - invalid_shipping_amount
2.0.16Change credit_amount_requested, annual_income in BuyerApplication from string to integer
2.0.17Modify charge endpoints to allow for optional metadata parameter
2.0.18Modify the validation pattern of year_established
2.0.19Add Payload of Webhook Event Types
2.0.20Add new payment terms - Net 90
2.0.21Add the daily.charge.activity webhook event
2.0.22Add buyer_client_reference_id and po_number to the daily.charge.activity webhook event, remove buyer_id
2.0.23Add errorFields attribute for 400 errors to indicate invalid input fields
2.0.24Add cancellation_comment attribute for Cancel a charge
2.0.25Add missing_program error code for Create a charge
2.0.26Add more description under Pre-authorization
2.0.27update transaction_date description in daily.charge.activity webhook

Introduction

MSTS provides a safe and easy way to extend credit to your business customers. We are aiming to provide the easiest B2B payment flow with straightforward integration with your e-commerce application.

The following image shows the integration flow for a standalone e-commerce application:

alt text

If your application involves a marketplace, the integration will be slightly different:

alt text

Once you are ready to integrate, you can follow the following steps:

Step 1. Create your API key

Login to https://app.msts.credit. Navigate to the API Keys screen by clicking the API Keys menu item in the menu. If your account has access to multiple programs, then you will need to select the program (located in the upper right of the screen). Click NEW API KEY button to create an API Key. When the key is generated, place the detail in secure storage. MSTS cannot reverse engineer your API key.

The API key must be used for all server-side interactions. The API key MUST NOT be used for client-side interactions.

Step 2. Register a webhook to receive important notifications

MSTS will notify you about new/changed buyers and payments. The buyer notification provides the ID to use when later referencing buyers.

MSTS will make best efforts to ensure you receive every notification. A HTTP response in the range of 200 to 299 will assist, letting us know not to try again.

MSTS operates two environments for you (Test and Production). They are identified by API key. Each environment has its own webhook.

Step 3. Register buyers

MSTS provides two ways to register buyers. Buyers can complete a MSTS credit application form or alternatively you can submit a server-side API request.

The specification for buyer credit application API lists all the required data to register buyer and apply for credit.

For the MSTS application form, buyers will be provided with a link to navigate to the form. The link contains the URL and query parameters that will pre-populate some fields in the application form. The supported parameters are:

client_reference_id : Required parameter - The ID to identify the buyer in your program.

first_transacted_date : Optional parameter - The first transaction date of the buyer in your program. The date must be in YYYY-MM-DD format.

total_transacted_amount : Optional parameter - The total transaction amount of the buyer.

current_transaction_amount : Optional parameter - The current transaction amount in the shopping cart.

ecommerce_url : Optional parameter - The URL for the buyer to return to the ecommerce site.

An example link with query parameter is as follows https://my_program.msts.credit/apply?client_reference_id=123456&first_transacted_date=2017-01-30&total_transacted_amount=10000

You will need to generate the URL for each buyer, so they can visit the form with necessary query parameters. You will include a link in your site for the buyer to apply for credit.

Step 4. Modify your ecommerce site to integrate auth/charge API's.

Your site needs to include a way to apply for credit as described in Step 3.

Your site also needs to offer the payment method during checkout. This might be displayed when buyers have an approved credit line (see Step 2).

When a buyer selects the payment method, your site will optionally submit a server-side API request to pre-authorize the amount. This locks the amount from being used for other purchases.

When you fulfill an order, your site will submit a server-side API request to charge the buyer. This may reference a pre-authorization. A charge can exceed the pre-authorization amount upto the buyers available credit.

4.1. Pre-authorization (optional)

A pre-authorization places a temporary lock on an amount of credit with a buyer. It ensures that these funds are available to charge when an order is fulfilled.

A single pre-authorization can be used for multiple charges. This provides flexibility to charge incrementally as an order is fulfilled.

Best practice is to submit a preauthorization before submitting a charge. This blocks an amount on the buyer's credit line and verifies that the buyer has enough credit available for the future charge. Preauthorizations will be rejected if the buyer's account is not in an active status. Once a preauthorization is successfully accepted, MSTS will honor that preauthorization regardless of the buyer's account status. Note that preauthorizations will expire after a program specific period of time.

If the seller elects not to submit a preauthorization and only a charge, MSTS will check the buyer's account status and the buyer's available credit before accepting the charge. If the buyer does not have the necessary credit available or is not in an active status, the charge will be rejected.

4.2. Charges

Charges initiate seller payments and buyer invoices. Where a pre-authorization was used, you need to include the id of the pre-authorization to reduce the pre-authorized amount remaining.

4.3. Pre-authorization cancellations

A pre-authorization can be cancelled. Cancellation will free any remaining credit that is locked by this pre-authorization.

4.4. Cancel Charges

A charge must be cancelled when an order is cancelled or partially refunded. If creating a new charge for a revised amount (in the case of refunds) include the previous charge id. MSTS will refund the seller fee of the original charge. You must specify a comment when creating a charge that references a previous charge. This information will be displayed on the buyers invoice. alt text

Errors

HTTP response codes are used to indicate the success or failure of an API request.

Status Code RangeDescription
2xxIndicates success.
4xxIndicates a bad request was made. Eg. data in the payload provided was not valid.
5xxIndicates an error occurred with our server. This should rarely happen

If an error occurs, an error objects will be returned. The error object contains a code, which could be used to programatically handle the error. A message field is also included, containing a text description of the error. Some 400 errors may also include a validationErrors field containing an array of additional data related to the error. For buyer_application, 400 errors might have errorFields attribute to indicate invalid fields.

Sample error response:

 {
   "code": "invalid_seller",
   "message": "Seller with id '7365581a-eedb-4c96-bbf9-f97bac59f551' is non-existent or inactive."
 }

The list of possible error codes are as follow:

Error CodeDescription
amount_mismatchThe amounts specified in the charge are not equal to the sum of the amounts in charge details
authorization.missing_required_permissionUser does not have the correct role for accessing the API endpoint
authorization.unauthenticated_not_allowedWrong API key. Unauthenticated access not allowed for API endpoint
buyer_already_createdA buyer has already exists
client_reference_id_already_existsThe client reference ID has been used for a buyer in the same program
detail_amount_mismatchThe amounts specified in the charge details are not equal to the subtotal of the detail in charge details
discount_amount_mismatchThe discount amount specified in the charge is not equal to the sum of the discount amount in charge details
email_already_existsThe email has been used for a buyer
internal_errorInternal server error
invalid_buyerBuyer for the given ID does not exist or inactive
invalid_inputOne of the request inputs is not valid
invalid_preauthorizationInvalid preauthorization for the ID specified
invalid_programSeller and Buyer are not in the same program
invalid_poPurchase Order number is invalid or does not match expected format
invalid_sellerSeller for the given ID does not exist or inactive
invalid_shipping_amountShipping amount + shipping tax amount - shipping discount amount can not be less than 0
method_not_allowedMethod is not allowed
missing_programThe associated Program was not found
new_application_not_allowedThe program is configured to not allow any new applications
po_requiredPurchase Order number is required
preauthorization_amount_too_lowThe updated preauthorization amount is lower than the captured amount.
preauthorization_invalid_amountThe updated preauthorization amount must be less than the original amount.
preauthorization_invalid_statusPreauthorization with Expired, Cancelled or Rejected status can't be cancelled or updated
preauthorization_po_requiredPurchase Order number is required for this buyer's preauthorization
program_not_foundThe program in the buyer application doesn't exist
resource_not_foundNo information is found for the requested ID
return_amount_mismatchThe Sum of return amount plus total amount must equal original amount of charge
return_invalid_amountInvalid return amount. The return amount cannot exceed the charge amount.
return_invalid_chargeInvalid charge for the ID specified
return_invalid_total_amountInvalid total amount - not equal to sum of detail subtotal plus shipping and shipping tax(if provided) minus shipping discount(if provided)
return_invalid_amount_use_refundInvalid return amount - amount equals remaining amount - use Cancel a charge instead
tax_amount_mismatchThe tax amount specified in the charge is not equal to the sum of the tax amount in charge details
unsupported_currencyThe specified currency is not supported for the seller
validation.body_not_matching_json_schemaRequest body failed JSON schema validation
validation.invalid_query_parameterThe value for the query parameter is invalid
validation.invalid_path_parameterThe value for the path parameter is invalid
validation.unsupported_media_typeUnsupported media type

Common Variables

Unless otherwise specified, attributes are in the following common formats.

VariableDescriptionExample
dateDates are in ISO 8601/RFC3339 'full-date' format.2018-01-30
date-timeDates/times are in ISO 8601/RFC3339 'date-time' format.2018-07-12T02:00:25.535Z
amountsAmounts are in the smallest currency unit, for example 100 for JPY 100, 100 for USD 1, 1000 for BHD 1.50000
uuidUUIDs adhere to UUID v4 (random)cf771e8a-5c1a-462f-b4c9-fc745f02d0de

Authentication

Requests are authenticated via bearer authentication. You will need an API Key which can be obtain by following Step 1 in the Introduction section.

The API Key can be used differently depending on the context.

Authentication via HTTP Basic Auth

For example if your API Key is 13bdb78c-6169-43de-a6ac-c1c771e4f688, you provide it as the basic auth username value. You do not need to provide a password.

Example curl GET request using basic auth:

 curl -X GET app.msts.credit/api/v20180807/charges -u 13bdb78c-6169-43de-a6ac-c1c771e4f688: 
The colon on the end stops curl from asking for a password

Authentication via Bearer Auth

The API Key can be provided via a Bearer token header.

For example if your api key is 13bdb78c-6169-43de-a6ac-c1c771e4f688, you would include the 'Authorization' header with the value Bearer 13bdb78c-6169-43de-a6ac-c1c771e4f688.

Example curl GET request with authentication:

 curl -H 'Authorization: Bearer 13bdb78c-6169-43de-a6ac-c1c771e4f688' -H "accept: application/json" -X GET app.msts.credit/api/v20180807/charges/f52cd8cd-3728-44d7-85ff-95efbef46e3d 

API requests must be made over https and must include authentication, or else they will fail.

bearerAuth

provide api key in header as Authorisation: Bearer [API KEY]

Security scheme type: API Key
header parameter name: Authorization: Bearer [API-KEY]

basicAuth

provide api key as username

Security scheme type: HTTP
HTTP Authorization Scheme basic

Preauthorization

Create a preauthorization

Reserves an amount of available credit

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
seller_id
required
string^(?:{[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7}}|[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7})$

Universally unique identifier (UUID).

buyer_id
required
string^(?:{[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7}}|[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7})$

Universally unique identifier (UUID).

currency
required
string

Three-letter ISO currency code in uppercase. Must be a supported currency for the seller.

preauthorized_amount
required
integer [ 1 .. 214748364 ]

Amount to be preauthorized.

po_number
string [ 0 .. 200 ] characters

PO Number. This may be required by some buyers/sellers based on their configuration. Format validations may also be applied based on requirements.

Responses

201

The preauthorization was created successfully

400

Bad request

Error CodeDescription
validation.body_not_matching_json_schemaRequest body failed JSON schema validation
invalid_sellerSeller for the given ID does not exist or inactive
invalid_buyerBuyer for the given ID does not exist or inactive
invalid_programSeller and Buyer are not in the same program
unsupported_currencyThe specified currency is not supported for the seller
preauthorization_po_requiredPurchase Order number is required for this buyer's preauthorization
preauthorization_invalid_poPurchase Order number is invalid or does not match expected format
invalid_inputOne of the request inputs is not valid

401

Authentication is missing or invalid

Error CodeDescription
authorization.unauthenticated_not_allowedUnauthenticated access

402

The preauthorization was rejected because of insufficient credit

403

Permission to the requested resource is denied

Error CodeDescription
authorization.missing_required_permissionUser does not have the correct role for accessing

415

Unsupported media type

Error CodeDescription
validation.unsupported_media_typeUnsupported media type

500

Internal server error

Error CodeDescription
internal_errorInternal server error

502

Bad gateway

Error CodeDescription
bad_gatewayInvalid response from the upstream server

post /preauthorizations
https://app.msts.credit/api/v20180807/preauthorizations

Request samples

application/json
Copy
Expand all Collapse all
{
  • "seller_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "buyer_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "currency": "string",
  • "preauthorized_amount": 1,
  • "po_number": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "seller_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "buyer_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "currency": "string",
  • "preauthorized_amount": 1,
  • "captured_amount": 0,
  • "foreign_exchange_fee": 0,
  • "status": "Preauthorized",
  • "po_number": "string",
  • "expires": "2018-07-12T02:00:25.535Z",
  • "created": "2018-07-12T02:00:25.535Z",
  • "modified": "2018-07-12T02:00:25.535Z"
}

Cancel a preauthorization

Cancels a credit reservation

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string^(?:{[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7}}|[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7})$
Example: "cf771e8a-5c1a-462f-b4c9-fc745f02d0de"

The id of the preauthorization. Universally unique identifier (UUID).

Responses

200

The preauthorization was cancelled

400

Bad request

Error CodeDescription
preauthorization_invalid_statusPreauthorization with Expired, Cancelled or Rejected status can't be cancelled or updated
invalid_inputOne of the request inputs is not valid

401

Authentication is missing or invalid

Error CodeDescription
authorization.unauthenticated_not_allowedUnauthenticated access

403

Permission to the requested resource is denied

Error CodeDescription
authorization.missing_required_permissionUser does not have the correct role for accessing

404

Not found

Error CodeDescription
resource_not_foundNo information is found for the requested ID

500

Internal server error

Error CodeDescription
internal_errorInternal server error

delete /preauthorizations/{id}
https://app.msts.credit/api/v20180807/preauthorizations/{id}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "seller_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "buyer_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "currency": "string",
  • "preauthorized_amount": 1,
  • "captured_amount": 0,
  • "foreign_exchange_fee": 0,
  • "status": "Preauthorized",
  • "po_number": "string",
  • "expires": "2018-07-12T02:00:25.535Z",
  • "created": "2018-07-12T02:00:25.535Z",
  • "modified": "2018-07-12T02:00:25.535Z"
}

Update preauthorization amount

Update a preauthorization amount to reduce the reserved credit

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string
Example: "cf771e8a-5c1a-462f-b4c9-fc745f02d0de"

The id of the preauthorization. Universally unique identifier (UUID).

Request Body schema: application/json
preauthorized_amount
required
integer [ 1 .. 214748364 ]

The preauthorization amount to update to. The updated amount can not be greater than previous preauthorization amount. The updated amount can not less than the captured amount that has been used by charges.

Responses

201

The preauthorization amount was updated

400

Bad request

Error CodeDescription
validation.body_not_matching_json_schemaRequest body failed JSON schema validation
preauthorization_invalid_statusPreauthorization with Expired, Cancelled or Rejected status can't be cancelled or updated
preauthorization_invalid_amountThe updated preauthorization amount cannot exceed the original amount.
preauthorization_amount_too_lowThe updated preauthorization amount is lower than the captured amount.
invalid_inputOne of the request inputs is not valid

401

Authentication is missing or invalid

Error CodeDescription
authorization.unauthenticated_not_allowedUnauthenticated access

403

Permission to the requested resource is denied

Error CodeDescription
authorization.missing_required_permissionUser does not have the correct role for accessing

404

Not found

Error CodeDescription
resource_not_foundNo information is found for the requested ID

415

Unsupported media type

Error CodeDescription
validation.unsupported_media_typeUnsupported media type

500

Internal server error

Error CodeDescription
internal_errorInternal server error

502

Bad gateway

Error CodeDescription
bad_gatewayInvalid response from the upstream server

post /preauthorizations/{id}
https://app.msts.credit/api/v20180807/preauthorizations/{id}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "preauthorized_amount": 1
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "seller_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "buyer_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "currency": "string",
  • "preauthorized_amount": 1,
  • "captured_amount": 0,
  • "foreign_exchange_fee": 0,
  • "status": "Preauthorized",
  • "po_number": "string",
  • "expires": "2018-07-12T02:00:25.535Z",
  • "created": "2018-07-12T02:00:25.535Z",
  • "modified": "2018-07-12T02:00:25.535Z"
}

Charge

Create a charge

Capture an amount from available credit

Authorizations:
bearerAuthbasicAuth
Request Body schema: application/json
seller_id
required
string^(?:{[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7}}|[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7})$

Universally unique identifier (UUID).

buyer_id
required
string^(?:{[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7}}|[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7})$

Universally unique identifier (UUID).

currency
required
string

Three-letter ISO currency code in uppercase. Must be a supported currency for the seller.

total_amount
required
integer [ 1 .. 214748364 ]

The total amount of the charge. It includes the sum of all details subtotal + shipping amount + shipping tax amount - shipping discount amount + foreign exchange fee.

tax_amount
required
integer [ 0 .. 214748364 ]

Sum of the tax amount in each detail.

shipping_amount
integer [ 0 .. 214748364 ]

Shipping amount of the charge.

shipping_tax_amount
integer [ 0 .. 214748364 ]

The tax on the shipping amount. Use this attribute to specify shipping tax amount if shipping amount is not including tax.

shipping_discount_amount
integer [ 0 .. 214748364 ]

The discount on the shipping amount. Use this attribute to specify shipping discount amount if shipping amount is not including discount.

discount_amount
integer [ 0 .. 214748364 ]

Sum of the discount amount in each detail.

order_url
required
string <url>

The URL of the order on the ecommerce site.

order_number
required
string

Specific order number generated from ecommerce site.

po_number
string [ 0 .. 200 ] characters

PO Number. This may be required by some buyers/sellers based on their configuration. Format validations may also be applied based on requirements.

preauthorization_id
string^(?:{[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7}}|[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7})$

The id of the preauthorization for this charge. Universally unique identifier (UUID).

previous_charge_id
string^(?:{[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7}}|[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7})$

The id of a charge related to this charge. This is normally use to identify a charge that was cancelled and recreated as the current charge. Universally unique identifier (UUID).

comment
string [ 0 .. 1000 ] characters

Comments for this charge.

details
required
Array of object (ChargeDetails)
metadata
Array of object (Metadata)

Additional metadata for the Charge. This takes a minimum of 1 item and a maximum of 5.

Responses

201

The new charge was created successfully

400

Bad request

Error CodeDescription
validation.body_not_matching_json_schemaRequest body failed JSON schema validation
invalid_sellerSeller for the given ID does not exist or inactive
invalid_buyerBuyer for the given ID does not exist or inactive
invalid_programSeller and Buyer are not in the same program
missing_programThe associated Program was not found
unsupported_currencyThe specified currency is not supported for the seller
invalid_preauthorizationInvalid preauthorization for the ID specified
amount_mismatchThe amounts specified in the charge are not equal to the sum of the amounts in charge details
detail_amount_mismatchThe amounts specified in the charge details are not equal to the subtotal of the detail in charge details
po_requiredPurchase Order number is required
invalid_poPurchase Order number is invalid or does not match expected format
invalid_inputOne of the request inputs is not valid
tax_amount_mismatchThe tax amount specified in the charge is not equal to the sum of the tax amount in charge details
discount_amount_mismatchThe discount amount specified in the charge is not equal to the sum of the discount amount in charge details
invalid_shipping_amountShipping amount + shipping tax amount - shipping discount amount can not be less than 0

401

Authentication is missing or invalid

Error CodeDescription
authorization.unauthenticated_not_allowedUnauthenticated access

402

The charge was rejected because of insufficient credit

403

Permission to the requested resource is denied

Error CodeDescription
authorization.missing_required_permissionUser does not have the correct role for accessing

415

Unsupported media type

Error CodeDescription
validation.unsupported_media_typeUnsupported media type

500

Internal server error

Error CodeDescription
internal_errorInternal server error

502

Bad gateway

Error CodeDescription
bad_gatewayInvalid response from the upstream server

post /charges
https://app.msts.credit/api/v20180807/charges

Request samples

application/json
Copy
Expand all Collapse all
{
  • "seller_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "buyer_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "currency": "string",
  • "total_amount": 1,
  • "tax_amount": 0,
  • "shipping_amount": 0,
  • "shipping_tax_amount": 0,
  • "shipping_discount_amount": 0,
  • "discount_amount": 0,
  • "order_url": "string",
  • "order_number": "string",
  • "po_number": "string",
  • "preauthorization_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "previous_charge_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "comment": "string",
  • "details":
    [
    ],
  • "metadata":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "seller_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "buyer_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "status": "Created",
  • "currency": "string",
  • "total_amount": 1,
  • "tax_amount": 0,
  • "shipping_amount": 0,
  • "shipping_tax_amount": 0,
  • "shipping_discount_amount": 0,
  • "discount_amount": 0,
  • "foreign_exchange_fee": 0,
  • "original_total_amount": 1,
  • "paid_amount_currency": "string",
  • "paid_amount": 0,
  • "order_url": "string",
  • "order_number": "string",
  • "po_number": "string",
  • "previous_charge_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "comment": "string",
  • "due_date": "2018-01-30T00:00:00.000Z",
  • "created": "2018-07-12T02:00:25.535Z",
  • "modified": "2018-07-12T02:00:25.535Z",
  • "details":
    [
    ],
  • "metadata":
    [
    ],
  • "cancellation_comment": "string",
  • "cancellation_reason": "Delivery Refused",
  • "return_comment": "string",
  • "return_reason": "Delivery Refused"
}

List charges

Returns a list of charges

Authorizations:
bearerAuthbasicAuth
query Parameters
page_size
integer

Number of charges to list per page

page_number
integer

Page number

from_date
string <date-time>
Example: "2018-07-12T02:00:25.535Z"

The from date to list charges.

to_date
string <date-time>
Example: "2018-07-12T02:00:25.535Z"

The to date to list charges.

Responses

200

The list of charges

400

Bad request

Error CodeDescription
validation.invalid_query_parameterThe value for the query parameter is invalid

401

Authentication is missing or invalid

Error CodeDescription
authorization.unauthenticated_not_allowedUnauthenticated access

403

Permission to the requested resource is denied

Error CodeDescription
authorization.missing_required_permissionUser does not have the correct role for accessing

500

Internal server error

Error CodeDescription
internal_errorInternal server error

get /charges
https://app.msts.credit/api/v20180807/charges

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Cancel a charge

The charge to cancel because of an order cancellation or full refund

path Parameters
id
required
string^(?:{[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7}}|[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7})$
Example: "cf771e8a-5c1a-462f-b4c9-fc745f02d0de"

The id of the charge. Universally unique identifier (UUID).

Request Body schema: application/json
reason
required
string (CancellationReason)
Enum:"Delivery Refused" "Merchandise Damaged" "Merchandise Defective" "Duplicate Shipment" "Duplicate Consignment" "Other"

cancellation_reason will only show up for cancelled charge.

cancellation_comment
string [ 0 .. 1000 ] characters

The comment associated with cancelling the charge. The cancellation_comment will only show up if it has been provided.

Responses

200

The cancelled charge

400

Bad request

Error CodeDescription
validation.body_not_matching_json_schemaRequest body failed JSON schema validation
invalid_inputOne of the request inputs is not valid

401

Authentication is missing or invalid

Error CodeDescription
authorization.unauthenticated_not_allowedUnauthenticated access

403

Permission to the requested resource is denied

Error CodeDescription
authorization.missing_required_permissionUser does not have the correct role for accessing

404

Not found

Error CodeDescription
resource_not_foundNo information is found for the requested ID

415

Unsupported media type

Error CodeDescription
validation.unsupported_media_typeUnsupported media type

500

Internal server error

Error CodeDescription
internal_errorInternal server error

502

Bad gateway

Error CodeDescription
bad_gatewayInvalid response from the upstream server

delete /charges/{id}
https://app.msts.credit/api/v20180807/charges/{id}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "reason": "Delivery Refused",
  • "cancellation_comment": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "seller_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "buyer_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "status": "Created",
  • "currency": "string",
  • "total_amount": 1,
  • "tax_amount": 0,
  • "shipping_amount": 0,
  • "shipping_tax_amount": 0,
  • "shipping_discount_amount": 0,
  • "discount_amount": 0,
  • "foreign_exchange_fee": 0,
  • "original_total_amount": 1,
  • "paid_amount_currency": "string",
  • "paid_amount": 0,
  • "order_url": "string",
  • "order_number": "string",
  • "po_number": "string",
  • "previous_charge_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "comment": "string",
  • "due_date": "2018-01-30T00:00:00.000Z",
  • "created": "2018-07-12T02:00:25.535Z",
  • "modified": "2018-07-12T02:00:25.535Z",
  • "details":
    [
    ],
  • "metadata":
    [
    ],
  • "cancellation_comment": "string",
  • "cancellation_reason": "Delivery Refused",
  • "return_comment": "string",
  • "return_reason": "Delivery Refused"
}

Retrieve a charge

Returns the details of a charge

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string^(?:{[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7}}|[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7})$
Example: "cf771e8a-5c1a-462f-b4c9-fc745f02d0de"

The charge id

Responses

200

The id of the charge. Universally unique identifier (UUID).

400

Bad request

Error CodeDescription
validation.invalid_path_parameterThe value for the path parameter is invalid

401

Authentication is missing or invalid

Error CodeDescription
authorization.unauthenticated_not_allowedUnauthenticated access

403

Permission to the requested resource is denied

Error CodeDescription
authorization.missing_required_permissionUser does not have the correct role for accessing

404

Not found

Error CodeDescription
resource_not_foundNo information is found for the requested ID

500

Internal server error

Error CodeDescription
internal_errorInternal server error

get /charges/{id}
https://app.msts.credit/api/v20180807/charges/{id}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "seller_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "buyer_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "status": "Created",
  • "currency": "string",
  • "total_amount": 1,
  • "tax_amount": 0,
  • "shipping_amount": 0,
  • "shipping_tax_amount": 0,
  • "shipping_discount_amount": 0,
  • "discount_amount": 0,
  • "foreign_exchange_fee": 0,
  • "original_total_amount": 1,
  • "paid_amount_currency": "string",
  • "paid_amount": 0,
  • "order_url": "string",
  • "order_number": "string",
  • "po_number": "string",
  • "previous_charge_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "comment": "string",
  • "due_date": "2018-01-30T00:00:00.000Z",
  • "created": "2018-07-12T02:00:25.535Z",
  • "modified": "2018-07-12T02:00:25.535Z",
  • "details":
    [
    ],
  • "metadata":
    [
    ],
  • "cancellation_comment": "string",
  • "cancellation_reason": "Delivery Refused",
  • "return_comment": "string",
  • "return_reason": "Delivery Refused"
}

Return a charge

Create a partial return of a charge. Return amount will be in same currency to the charge currency.

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string^(?:{[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7}}|[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7})$
Example: "cf771e8a-5c1a-462f-b4c9-fc745f02d0de"

The id of the charge. Universally unique identifier (UUID).

Request Body schema: application/json
return_amount
required
integer [ 1 .. 214748364 ]

The return amount of the charge

total_amount
required
integer [ 1 .. 214748364 ]

The new total amount of the charge

tax_amount
required
integer [ 0 .. 214748364 ]

The new tax amount of the charge

shipping_amount
required
integer [ 0 .. 214748364 ]

The new shipping amount of the charge

shipping_tax_amount
integer [ 0 .. 214748364 ]

The new shipping tax amount of the charge

shipping_discount_amount
integer [ 0 .. 214748364 ]

The new shipping discount amount of the charge

discount_amount
integer [ 0 .. 214748364 ]

The new discount amount of the charge

details
required
Array of object (ChargeDetails)

The new charge detail items.

metadata
Array of object (Metadata)

Additional metadata for the Charge. This takes a minimum of 1 item and a maximum of 5.

return_reason
required
string (ReturnReason)
Enum:"Delivery Refused" "Merchandise Damaged" "Merchandise Defective" "Duplicate Shipment" "Duplicate Consignment" "Other"

return_reason will only show up for returned charge.

return_comment
string [ 0 .. 1000 ] characters

The comment associated with returning the charge. Return_comment will only show up for returned charge.

Responses

201

The new return was created successfully

400

Bad request

Error CodeDescription
validation.body_not_matching_json_schemaRequest body failed JSON schema validation
validation.unsupported_media_typeUnsupported media type
return_invalid_chargeInvalid charge for the ID specified
return_invalid_amountInvalid return amount. The return amount cannot exceed the charge amount.
return_invalid_amount_use_refundInvalid return amount - amount equals remaining amount - use Cancel a charge instead.
return_invalid_total_amountInvalid total amount - not equal to sum of detail subtotal plus shipping and shipping tax(if provided) minus shipping discount(if provided)
detail_amount_mismatchThe amounts specified in the charge details are not equal to the subtotal of the detail in charge details
return_amount_mismatchThe Sum of return amount plus total amount must equal original amount of charge
invalid_inputOne of the request inputs is not valid
tax_amount_mismatchThe tax amount specified in the charge is not equal to the sum of the tax amount in charge details
discount_amount_mismatchThe discount amount specified in the charge is not equal to the sum of the discount amount in charge details
invalid_shipping_amountShipping amount + shipping tax amount - shipping discount amount can not be less than 0

401

Authentication is missing or invalid

Error CodeDescription
authorization.unauthenticated_not_allowedUnauthenticated access

403

Permission to the requested resource is denied

Error CodeDescription
authorization.missing_required_permissionUser does not have the correct role for accessing

500

Internal server error

Error CodeDescription
internal_errorInternal server error

502

Bad gateway

Error CodeDescription
bad_gatewayInvalid response from the upstream server

post /charges/{id}
https://app.msts.credit/api/v20180807/charges/{id}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "return_amount": 1,
  • "total_amount": 1,
  • "tax_amount": 0,
  • "shipping_amount": 0,
  • "shipping_tax_amount": 0,
  • "shipping_discount_amount": 0,
  • "discount_amount": 0,
  • "details":
    [
    ],
  • "metadata":
    [
    ],
  • "return_reason": "Delivery Refused",
  • "return_comment": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "seller_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "buyer_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "status": "Created",
  • "currency": "string",
  • "total_amount": 1,
  • "tax_amount": 0,
  • "shipping_amount": 0,
  • "shipping_tax_amount": 0,
  • "shipping_discount_amount": 0,
  • "discount_amount": 0,
  • "foreign_exchange_fee": 0,
  • "original_total_amount": 1,
  • "paid_amount_currency": "string",
  • "paid_amount": 0,
  • "order_url": "string",
  • "order_number": "string",
  • "po_number": "string",
  • "previous_charge_id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "comment": "string",
  • "due_date": "2018-01-30T00:00:00.000Z",
  • "created": "2018-07-12T02:00:25.535Z",
  • "modified": "2018-07-12T02:00:25.535Z",
  • "details":
    [
    ],
  • "metadata":
    [
    ],
  • "cancellation_comment": "string",
  • "cancellation_reason": "Delivery Refused",
  • "return_comment": "string",
  • "return_reason": "Delivery Refused"
}

Buyer

Gets the status and credit information for a buyer

Retrieve the status, credit approved, credit balance and credit held by pre-authorization for a buyer

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string^(?:{[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7}}|[0-9a-fA-F]{4}(?:-?[0-9a-fA-F]{4}){7})$
Example: "cf771e8a-5c1a-462f-b4c9-fc745f02d0de"

The buyer id

Responses

200

The status and credit information for a buyer

400

The operation failed because of an error. Possible error code are

Error CodeDescription
validation.invalid_path_parameterThe value for the path parameter is invalid

401

Authentication is missing or invalid

Error CodeDescription
authorization.unauthenticated_not_allowedUnauthenticated access

403

Permission to the requested resource is denied

Error CodeDescription
authorization.missing_required_permissionUser does not have the correct role for accessing

404

Not found

Error CodeDescription
resource_not_foundNo information is found for the requested ID

500

Internal server error

Error CodeDescription
internal_errorInternal server error

get /buyers/{id}/status
https://app.msts.credit/api/v20180807/buyers/{id}/status

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "cf771e8a-5c1a-462f-b4c9-fc745f02d0de",
  • "business_name": "string",
  • "client_reference_id": "string",
  • "status": "Active",
  • "currency":
    [
    ],
  • "credit_approved": 0,
  • "credit_balance": 0,
  • "credit_preauthorized": 0
}

Webhook

Create a webhook

Subscribes an endpoint to receive out-of-band data relating to system events for buyers, sellers and preauthorizations under a program.

When these events are occur, the webhook will post the data to the URL provided.

When creating webhooks, you can specify an http header and payload to be sent with each webhook event for authorization purposes.

If during the posting of events to your host the http status code is 200-299, the event is considered delivered.

If other status codes are received, they are reported to the client via email, and the service will attempt to resend the webhook, backing off exponentially.

Webhook event Payloads

There are four types of webhook events that notify you of events in your program:

When these events occur, the appropriate payload will be posted any webhook subscriptions you have created.

The details for each event payload follows.

Event Type: buyer.status


This event occurs if buyer status, business name, credit approved, credit balance or credit preauthorized have changed. The example payload that will be sent out:

  {
    "event_type": "buyer.status",
    "data": {
      "id": "a1c9b905-c5ce-4d41-9a6f-bfe597a75736",
      "business_name": "AAABusiness",
      "client_reference_id": "AAABusiness",
      "status": "Active",
      "currency": "USD",
      "credit_approved": 1000000,
      "credit_balance": 800000,
      "credit_preauthorized": 200000
    },
    "timestamp": "2018-08-06T00:20:31.535Z"
  }

Event Type: daily.charge.activity


This event occurs once per day. It returns data for all charges (including refunds and cancellations) created in the last 24 hours. Example:

  {
    "event_type": "daily.charge.activity",
    "data": [
      {
        "buyer_business_name": "AAABusiness",
        "buyer_client_reference_id": "shopify-customer-123",
        "buyer_terms_in_days": 15,
        "charge_id": "839aebc8-bdde-4914-838f-abdca845dd06",
        "currency": "USD",
        "disbursement_terms_in_days": 10,
        "invoice_number": "0b003c49",
        "order_number": "842",
        "po_number": "456",
        "seller_business_name": "BBBBusiness",
        "transaction_amount": 12345,
        "transaction_date": "2018-08-05",
        "type": "Charge"
      }
    ],
    "timestamp": "2018-08-06T00:20:31.535Z"
  }

Event Type: seller.charge.disbursed


This event occurs if there is payment disbursed to the seller.

The disbursed_amount is the amount the buyer will be paid, the fee_amount is the total fees retained for this disbursement.

Example:

  {
    "event_type": "seller.charge.disbursed",
    "data": [
      {
        "charge_id": "a1c9b905-c5ce-4d41-9a6f-bfe597a75736",
        "currency": "USD",
        "disbursed_amount": 9900,
        "fee_amount": -100,
        "fees": [
          {
            "fee_amount": -100,
            "rate": "100",
            "rate_type": "percentage",
            "fee_type": "transaction_fee"
          }
        ]
      }
    ],
    "timestamp": "2018-08-06T00:20:31.535Z"
  }

Charge Return / Charge Cancellation

The following section will show when a charge is returned or cancelled, depending on if it has been paid (disbursed) to the seller, that different fees are due.

Initial Charge

Charge ID Total Amount Fee
a1c9b905-c5ce-4d41-9a6f-bfe597a75736 $100.00 $1.00

Charge Return - prior to disbursement

This scenario covers returning a part of a charge where the payment has NOT yet been paid (disbursed) to the seller.

Return

Return Amount Remaining Charge Total
$25.00 $75.00

The charge was created and part of the charge was returned before the seller was paid via disbursement.

At disbursement, the remaining amount is paid, with fees being charged only on the remaining amount after the return was performed.

Action Buyer Amount Charge amount fee charged Due seller fee_amount disbursed_amount
Charge Created -10000 10000 -100 9900 NA NA
Charge Partial Return 2500 7500 25 7425 NA NA
seller.charge.disbursed NA NA 0 -75 7425

This will result in the following seller.charge.disbursed payload:

  {
    "event_type": "seller.charge.disbursed",
    "data": [
      {
        "charge_id": "a1c9b905-c5ce-4d41-9a6f-bfe597a75736",
        "currency": "USD",
        "disbursed_amount": 7425,
        "fee_amount": -75,
        "fees": [
          {
            "fee_amount": -75,
            "rate": "100",
            "rate_type": "percentage",
            "fee_type": "transaction_fee"
          }
        ]
      }
    ],
    "timestamp": "2018-08-06T00:20:31.535Z"
  }

Charge Return - post disbursement

When returning a part of a charge where the payment HAS been paid (disbursed) to the seller, the disbursed_amount shows a negative amount that will be recovered from the seller to cover the return.

In the scenario, the charge is created, disbursed to the seller, then a return is created and after that a disbursement is created to recover the funds from the buyer.

Action Buyer Amount charge amount fee charged Due seller fee_amount disbursed_amount
Charge Created -10000 10000 -100 9900 NA NA
seller.charge.disbursed NA NA 0 -100 9900
Charge Partial Return 2500 7500 -75 -2425 NA
seller.charge.disbursed NA NA 0 -25 -2500

In this case the seller was charged $25 for the return ("disbursed_amount" : -2500).

The retained fee amount is 25 cents ("fee_amount" : -25 ), as sellers are liable for fees on charges that have been paid (disbursed) to them.

  {
    "event_type": "seller.charge.disbursed",
    "data": [
      {
        "charge_id": "a1c9b905-c5ce-4d41-9a6f-bfe597a75736",
        "currency": "USD",
        "disbursed_amount": -2500,
        "fee_amount": -25,
        "fees": [
          {
            "fee_amount": -25,
            "rate": "100",
            "rate_type": "percentage",
            "fee_type": "transaction_fee"
          }
        ]
      }
    ],
    "timestamp": "2018-08-06T00:20:31.535Z"
  }

Charge Cancellation - prior to disbursement

If a charge is cancelled and has NOT been paid (disbursed) to the seller, a disbursed_amount of zero is returned, as nothing is due from the seller.

Action Buyer Amount Original charge amount fee charged Due seller fee_amount disbursed_amount
Charge Created -10000 10000 -100 9900 NA NA
Charge Cancelled 10000 0 100 -9900 NA NA
seller.charge.disbursed NA NA 0 NA