Payouts
Introduction

Merchant Warrior's Payouts API can be used to send funds to any number of nominated Australian bank accounts.

  1. Contact Merchant Warrior to enable this feature on your account. You will need to supply

    • A PayTo enabled bank account to fund your payouts
    • A mandate with Merchant Warrior to authorise debiting of your account to facilitate the payouts
    • A notification URL to receive updates about all of your payout statuses

  2. Initiate a Payouts batch with the Create Payouts method below *

    • This will debit your bank account via PayTo for a single amount to fund paying out all the payouts in your payouts batch.

  3. Once the funds are received via PayTo, Merchant Warrior will initiate payouts to all accounts specified in your batch via NPP *

  4. If any errors occur when sending funds via NPP, the payout will fall back to a DE payout *

    • If the payout fails via DE, the funds will be returned to you via an NPP transaction *

Notifications will be sent to your notify URL for all steps marked with *

Postman
A Postman collection is available here that demonstrates how to use the Payouts API.

Environments
Production: https://api.merchantwarrior.com
Sandbox: https://base.merchantwarrior.com

Sandbox Simulations

The following BSB and Account Numbers can be used in the Sandbox environment to simulate specific responses.

Scenario BSB Account Notifications
Successful NPP Payout 802950 123321 NPP approved
DE Fallback 802950 11111111 NPP declined, DE approved
DE Fallback Failure (Return Funds Success) 802950 13131313 NPP declined, DE returned
DE Fallback Failure (Return Funds Failed) 802950 14141414 NPP declined, DE declined
Invalid BSB 111111 123321
Create Payouts

Used to create a new payouts batch. Making this request will initiate the whole process, which includes debiting your nominated account for the full amount of all payouts in the batch, and sending payouts to all the nominated accounts.

Endpoint: /payout/process

Headers

Parameter Description
MW-MERCHANTID

The value of this parameter is provided to you by Merchant Warrior. Also known as your Merchant UUID.
Example: 4aa82af83c95d
MW-API-KEY

The value of this parameter is provided to you by Merchant Warrior.
Example: mz3dz5fp
MW-MESSAGEHASH

The verification hash is a combination of the HMAC SHA256 of your API Passphrase, and the entire JSON body. See MW-MESSAGEHASH (JSON) for information on how to construct the hash correctly.
Example: 59e5f6f02777398bfd5652d041f1e0d3e44e30587308c55c7053f5e7d4b3a48d
MW-API-VERSION

Must be set to 2.0 for this product.
Example: 2.0

JSON Body

Parameter Description
reference

Type: String
Format: Up to 32 characters
Required: Yes

This is the unique identifier for the payouts batch. Each batch requires you to generate a unique reference, which will be used in all notifications and lookup endpoints. If it is not unique, the entire payouts batch is rejected.
payouts

Type: Array
Required: Yes

An array of the payouts to be performed.
payee

Type: Object
Required: Yes

An object describing a single payout.
name

Type: String
Format: Up to 255 characters
Required: Yes

The name of the recipient receiving the payout.
address

Type: Object
Required: Yes

An object describing the address of the recipient of the payout.
street

Type: String
Format: Up to 255 characters
Required: Yes

The street of the recipient receiving the payout.
city

Type: String
Format: Up to 75characters
Required: Yes

The city of the recipient receiving the payout.
state

Type: String
Format: Up to 75 characters
Required: Yes

The state of the recipient receiving the payout.
postcode

Type: String
Format: Up to 10 characters
Required: Yes

The postcode of the recipient receiving the payout.
country

Type: String
Format: Up to 75 characters
Required: Yes

The country of the recipient receiving the payout.
contact

Type: Object
Required: No

An object describing the contact details of the recipient.
phone

Type: String
Format: Up to 25 characters
Required: No

The phone number of the recipient receiving the payout.
email

Type: String
Format: Up to 255 characters
Required: No

The email address of the recipient receiving the payout.
transaction

Type: Object
Required: Yes

An object describing the transaction details of the payout.
reference

Type: String
Format: Up to 32 characters
Required: Yes

The individual payout reference. This should be a string value used to uniquely identify the individual payout. If it is not unique, the individual payout will be deemed to be invalid and will be skipped.
product

Type: String
Format: Up to 255 characters
Required: Yes

The description of the payout. It does not need to be unique, should be human readable and describes what the payout is for.
amount

Type: Number
Required: Yes

The payout amount in dollars.
bsb

Type: String
Format: 6 digits
Required: Yes

The recipient's BSB number of where the funds should be sent. Must be a valid Australian BSB. If it is not, the individual payout is deemed to be invalid and will be skipped.
accNumber

Type: String
Required: Yes

The recipient's account number number of where the funds should be sent.

Copy 
{
    "reference": "TEST-000006",
    "payouts": [
        {
            "payee": {
                "name": "Successful MAP",
                "address": {
                    "street": "345 Ann Street",
                    "city": "Brisbane",
                    "state": "Queensland",
                    "postcode": "4127",
                    "country": "Australia"
                },
                "contact": {
                    "phone": "0411111111",
                    "email": "[email protected]"
                }
            },
            "transaction": {
                "reference":"1234",
                "product": "Gaming Winnings (Melbourne Cup)",
                "amount": 10.00,
                "bsb": "802950",
                "accNumber": "123321"
            }
        },
        {
            "payee": {
                "name": "Invalid Payee BSB",
                "address": {
                    "street": "345 Ann Street",
                    "city": "Brisbane",
                    "state": "Queensland",
                    "postcode": "4127",
                    "country": "Australia"
                },
                "contact": {
                    "phone": "0411111111",
                    "email": "[email protected]"
                }
            },
            "transaction": {
                "reference": "5678",
                "product": "Gaming Winnings (Melbourne Cup)",
                "amount": 20.00,
                "bsb": "111111",
                "accNumber": "123321"
            }
        },
        {
            "payee": {
                "name": "DE Fallback MAP",
                "address": {
                    "street": "345 Ann Street",
                    "city": "Brisbane",
                    "state": "Queensland",
                    "postcode": "4127",
                    "country": "Australia"
                },
                "contact": {
                    "phone": "0411111111",
                    "email": "[email protected]"
                }
            },
            "transaction": {
                "reference": "9101112",
                "product": "Gaming Winnings (Melbourne Cup)",
                "amount": 30.00,
                "bsb": "802950",
                "accNumber": "20220812"
            }
        }
    ]
}
{ "reference": "TEST-000006", "payouts": [ { "payee": { "name": "Successful MAP", "address": { "street": "345 Ann Street", "city": "Brisbane", "state": "Queensland", "postcode": "4127", "country": "Australia" }, "contact": { "phone": "0411111111", "email": "[email protected]" } }, "transaction": { "reference":"1234", "product": "Gaming Winnings (Melbourne Cup)", "amount": 10.00, "bsb": "802950", "accNumber": "123321" } }, { "payee": { "name": "Invalid Payee BSB", "address": { "street": "345 Ann Street", "city": "Brisbane", "state": "Queensland", "postcode": "4127", "country": "Australia" }, "contact": { "phone": "0411111111", "email": "[email protected]" } }, "transaction": { "reference": "5678", "product": "Gaming Winnings (Melbourne Cup)", "amount": 20.00, "bsb": "111111", "accNumber": "123321" } }, { "payee": { "name": "DE Fallback MAP", "address": { "street": "345 Ann Street", "city": "Brisbane", "state": "Queensland", "postcode": "4127", "country": "Australia" }, "contact": { "phone": "0411111111", "email": "[email protected]" } }, "transaction": { "reference": "9101112", "product": "Gaming Winnings (Melbourne Cup)", "amount": 30.00, "bsb": "802950", "accNumber": "20220812" } } ] }
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
Get Payouts

Used to retrieve the status of a payouts batch.

Endpoint: /payout/{{payoutId or reference}}/status

Headers

Parameter Description
MW-MERCHANTID

The value of this parameter is provided to you by Merchant Warrior. Also known as your Merchant UUID.
Example: 4aa82af83c95d
MW-API-KEY

The value of this parameter is provided to you by Merchant Warrior.
Example: mz3dz5fp
MW-MESSAGEHASH

The verification hash is a combination of the HMAC SHA256 of your API Passphrase, and URL path. See MW-MESSAGEHASH (GET) for information on how to construct the hash correctly.
Example: 59e5f6f02777398bfd5652d041f1e0d3e44e30587308c55c7053f5e7d4b3a48d
MW-API-VERSION

Must be set to 2.0 for this product.
Example: 2.0

Copy 
<?xml version="1.0"?>
<mwResponse>
  <responseCode>0</responseCode>
  <responseMessage>Operation successful</responseMessage>
  <result>
    <payoutId>b3ea1011-b32e-11ed-98bf-005056a5521a</payoutId>
    <reference>TEST-000001</reference>
    <status>complete</status>
  </result>
</mwResponse>
0 Operation successful b3ea1011-b32e-11ed-98bf-005056a5521a TEST-000001 complete 
{
    "responseCode": 0,
    "responseMessage": "Operation successful",
    "result": {
        "payoutId": "b3ea1011-b32e-11ed-98bf-005056a5521a",
        "reference": "TEST-000001",
        "status": "complete"
    }
}
{ "responseCode": 0, "responseMessage": "Operation successful", "result": { "payoutId": "b3ea1011-b32e-11ed-98bf-005056a5521a", "reference": "TEST-000001", "status": "complete" } }
Resend Notifications

Used to resend notifications for all payouts in a specified payouts batch. The notification(s) will be sent to your nominated notify URL. All notifications are chunked to 1000 payouts per request. If you have more payouts than this in your batch, you will receive multiple requests into your system.

Endpoint: /payout/{{payoutId or reference}}/notify

Statuses

Payouts and Payout Transactions follow a lifecycle of statuses, as shown below.

Payout

  • pending
  • processing
  • complete

Payout Transaction

  • approved (NPP)
  • declined (NPP)
    • pending (DE)
      • approved (DE)
      • returned (DE)
      • declined (DE)

Headers

Parameter Description
MW-MERCHANTID

The value of this parameter is provided to you by Merchant Warrior. Also known as your Merchant UUID.
Example: 4aa82af83c95d
MW-API-KEY

The value of this parameter is provided to you by Merchant Warrior.
Example: mz3dz5fp
MW-MESSAGEHASH

The verification hash is a combination of the HMAC SHA256 of your API Passphrase, and URL path. See MW-MESSAGEHASH (GET) for information on how to construct the hash correctly.
Example: 59e5f6f02777398bfd5652d041f1e0d3e44e30587308c55c7053f5e7d4b3a48d
MW-API-VERSION

Must be set to 2.0 for this product.
Example: 2.0

Copy 
{
  "payoutId": "c0978125-b66a-11ed-98bf-005056a5521a",
  "reference": "TEST-000005",
  "status": "complete",
  "payouts": [
    {
      "transactionId": "c68bc910-b66a-11ed-98bf-005056a5521a",
      "reference": "1234",
      "status": "approved",
      "amount": 10,
      "type": "MAP"
    },
    {
      "transactionId": "c809b535-b66a-11ed-98bf-005056a5521a",
      "reference": "9101112",
      "status": "declined",
      "amount": 30,
      "type": "MAP"
    },
    {
      "transactionId": "c8a33a3b-b66a-11ed-98bf-005056a5521a",
      "reference": "9101112",
      "status": "approved",
      "amount": 30,
      "type": "DE"
    }
  ]
}
{ "payoutId": "c0978125-b66a-11ed-98bf-005056a5521a", "reference": "TEST-000005", "status": "complete", "payouts": [ { "transactionId": "c68bc910-b66a-11ed-98bf-005056a5521a", "reference": "1234", "status": "approved", "amount": 10, "type": "MAP" }, { "transactionId": "c809b535-b66a-11ed-98bf-005056a5521a", "reference": "9101112", "status": "declined", "amount": 30, "type": "MAP" }, { "transactionId": "c8a33a3b-b66a-11ed-98bf-005056a5521a", "reference": "9101112", "status": "approved", "amount": 30, "type": "DE" } ] }
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
Copy 
<?xml version="1.0"?>
<mwResponse>
  <responseCode>0</responseCode>
  <responseMessage>Operation successful</responseMessage>
</mwResponse>
0 Operation successful 
{
    "responseCode": 0,
    "responseMessage": "Operation successful"
}
{ "responseCode": 0, "responseMessage": "Operation successful" }
Get Payout Transaction Status

Used to retrieve the status of a payout transaction.

Endpoint: /payout/{{payoutId or reference}}/transaction/{{transactionId or reference}}/status

Headers

Parameter Description
MW-MERCHANTID

The value of this parameter is provided to you by Merchant Warrior. Also known as your Merchant UUID.
Example: 4aa82af83c95d
MW-API-KEY

The value of this parameter is provided to you by Merchant Warrior.
Example: mz3dz5fp
MW-MESSAGEHASH

The verification hash is a combination of the HMAC SHA256 of your API Passphrase, and URL path. See MW-MESSAGEHASH (GET) for information on how to construct the hash correctly.
Example: 59e5f6f02777398bfd5652d041f1e0d3e44e30587308c55c7053f5e7d4b3a48d
MW-API-VERSION

Must be set to 2.0 for this product.
Example: 2.0

Get Payout Transaction Notify

Used to resend notifications for all payouts in a specified payouts batch. The notification(s) will be sent to your nominated notify URL.

Endpoint: /payout/{{payoutId or reference}}/transaction/{transactionId or reference}/notify

Headers

Parameter Description
MW-MERCHANTID

The value of this parameter is provided to you by Merchant Warrior. Also known as your Merchant UUID.
Example: 4aa82af83c95d
MW-API-KEY

The value of this parameter is provided to you by Merchant Warrior.
Example: mz3dz5fp
MW-MESSAGEHASH

The verification hash is a combination of the HMAC SHA256 of your API Passphrase, and URL path. See MW-MESSAGEHASH (GET) for information on how to construct the hash correctly.
Example: 59e5f6f02777398bfd5652d041f1e0d3e44e30587308c55c7053f5e7d4b3a48d
MW-API-VERSION

Must be set to 2.0 for this product.
Example: 2.0

Copy 
{
  "payoutId": "22efc529-c7b9-11ed-834f-005056b2764e",
  "reference": "TEST-000005",
  "status": "complete",
  "payouts": [
    {
      "transactionId": "271c378f-c7b9-11ed-834f-005056b2764e",
      "reference": 1234,
      "status": "approved",
      "amount": 10,
      "type": "NPP"
    }
  ]
}
{ "payoutId": "22efc529-c7b9-11ed-834f-005056b2764e", "reference": "TEST-000005", "status": "complete", "payouts": [ { "transactionId": "271c378f-c7b9-11ed-834f-005056b2764e", "reference": 1234, "status": "approved", "amount": 10, "type": "NPP" } ] }
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
No sample available
Copy 
<?xml version="1.0"?>
<mwResponse>
  <responseCode>0</responseCode>
  <responseMessage>Operation successful</responseMessage>
</mwResponse>
0 Operation successful 
{
    "responseCode": 0,
    "responseMessage": "Operation successful"
}
{ "responseCode": 0, "responseMessage": "Operation successful" }