Image Image Image Image

Payout

Image Image Image

Swipelocal Payout API Integration Guide

Image

1. Introduction & Overview

This document provides a comprehensive guide for integrating with the Swipelocal Payout (Withdrawal) S2S API. It covers the purpose, endpoints, authentication methods, data encryption, and usage guidelines to enable you to make secure payout requests, check balances, and verify transaction statuses.

Pre-Requisites

To use this API, you must have the following credentials, available from your Swipelocal dashboard:

  • Merchant ID (mid)
  • Salt Key
  • Secret Key
  • Your server's IP address must be allowlisted.

Base URL:

Production: https://payout.swipelocal.au/

2. Core API Endpoints

Endpoint Method Description
/v3/pay-request POST Initiate a payout to a beneficiary
/v3/get-balance POST Check your available account balance
/v3/get-status POST Check the status of a specific transaction

3. Data Encryption & Decryption

All sensitive data in requests and responses must be encrypted/decrypted using AES-256-CBC.

3.1. Step-by-Step: Data Encryption for Requests

  • Create a Request Object: Form a JSON object with the required parameters (e.g., for /v3/pay-request).

    Request:

    {

    "amount": "10.00",
    "currency": "AUD",
    "order_id": "8783193",
    "pay_mode": "AUAT",
    "sub_pay_mode": "BSB",
    "merchant_id": "UMZO7EHTTO3DH",
    "beneficiary": {
    "bank_acc_no": "083028",
    "name": "TestTest",
    "email": "[email protected]",
    "mobile": "610430467999",
    "address": "55street99",
    "city": "SouthManhaten",
    "pincode": "1234",
    "bsb": "987654321",
    "state": "MyState",
    "country": "AUS"
    }

    }

  • Convert to String: Flatten the JSON object into a string, using a tilde ~ as a separator between key-value pairs.
    Example:
     encrypt_str={"amount": "10.00"~"currency": "AUD"~"order_id": "8783193"~"pay_mode": "AUAT"~"sub_pay_mode": "BSB"~"merchant_id": "UMZO7EHTTO3DH"~"beneficiary": { "bank_acc_no": "083028"~"name": "Test Test"~"email": "[email protected]"~"mobile": "610430467999"~"address": "55 street 99"~"city": "South Manhaten"~"pincode": "1234"~"bsb": "987654321"~"state": "My State"~"country": "AUS"}}
  • Derive Encryption Keys:
    • IV (Initialization Vector): Use the first 16 characters of your Payout Secret Key.
    • Encryption Key (K): Use the next 32 characters of your Secret Key (i.e., characters 17 to 48).
  • Encrypt the String: Encrypt the string using AES-256-CBC with the derived IV and Key.
    • Example OpenSSL Command:

      • openssl enc -aes-256-cbc -in plaintext.txt -out encrypted_data.bin -K [YOUR_32_CHAR_KEY] -iv [YOUR_16_CHAR_IV]

  • Form the Final Request: The encrypted data (often Base64 encoded) is passed as the "data" field in the final request payload, alongside your "mid".
  • Final Request Structure: json

    {

    "mid": "iA************zo",
    "data":
    "FEZQmxMXriEfA50gP8ntBqxejQMnBFbeH8fzMSPTr0trrLadD5iKGHZqFCh4T1FG4WLxZRPEZpjypufaCSJJtdTVePIIH2xjIH4zspWsavFq9tq9nlZZt UOuEovvjvADVdWHq8KQY8p3YWo5jFlG1oVZkUfwsdLyNGPxpD2IiZ0Xsj9fh8Q1RfozgkDqxWwLzreGbxM0FT9l50YiPv8dwe3NFHAHY3nCVq6JiRflgu5Opo7 PYAaT5SEgASaiV1YquDzA3PHE5e2DfSusxVmulU5VUlz9HPIZ30xV7ZKNlH7vyda4RvcPLdYWsItrN3XMQZpUYvmIIZLt5bMtvdS3Do4WZgWV2NFnR4IsHk7M6 RnP1qht0Ept3l1SKofLkxLGMJtERUQXI0jlfkqjDwPaJ2Ap4qxWoQPvYeLvwn/FMvoXKU0U5eO5wwx2kQeNNS+JuqGcG/n7DLB3KZuiThgHZHHIHnaamyp"

    }

3.2. Step-by-Step: Data Decryption for Responses

  • Obtain Encrypted Data : Extract the encrypted string from the "data" field in the API response.

    • Example :
    {

    "data":
    "fMrCfhtikCMjS5Y3+HyHRgc3mt4JHracb2cJJlYypxjguhK88bJsm07F5TmLRvzXpLZXRXqvDSyV99phyv7cj7ilzeDjhH1VLMODY24IHJj8+aZj1e6MKVaWT J4x08UKlF6RfRcTftgO9vl0ut/0dmwc1mJR5iT9GTtToiUHf/kQBIiApT1gehntiA9Exbqz9QpyS+7ZsXZouKkK4btWUE1LW6izn0Sv1RhPbH2M0PucMVlBw C3rCUuglS/qFl2Xtq6HS7NO3+ZJ5hXnXbMKNN7FHdMDrsBh4bLfGSXsdkQtIB3RAfb340e/BzY9X3b30NBPoRT90hIpWyXpfFQuhnrDfQWdQc8Jg4BzYTZJt N6n9f3BlV0bGUTVPh+2D25+qZzOwmbqyGywebMP/Byx7Rr92HlPS3jat+Vf7C3pR05qGI1feHgTQk/2QC+gq6LuP4DI9GXGqhUH1MnHt8TV7AvKcIWVSN JswheMIl3IWrbkRUHVGtcjvEIYru42b7P4atFtcNKij/LDE8A1E3/qkUAtQEWQ8UVMLVrjZGA3REAfyVGLGH4HlGSXQKBa9VevyavMcxvIXXkApIuq05SnLo T6UIZr36LCxG7jzH+D1 EI4WtXxiVYbSYDiNWNGcQJy"

    }

  • Derive Decryption Keys : Use the same IV and Key derived from your Secret Key as in the encryption process.
    • IV: First 16 characters of Secret Key.
    • Key: Next 32 characters of Secret Key.

  • Decrypt the Data : Decrypt the data using AES-256-CBC with the derived IV and Key.

    • Example OpenSSL Command : openssl enc -d -aes-256-cbc -in encrypted_data.txt -out decrypted_data.txt -K -iv

  • Parse Decrypted Data : The decrypted data will be a readable JSON string containing the transaction details or response message.

Explanation of Command-Line Options:
  • -d: Decryption option.
  • -aes-256-cbc: Specifies the AES algorithm in CBC mode.
  • -in encrypted_data.txt: Input file containing encrypted data.
  • -out decrypted_data.txt: Output file for decrypted data.
  • -K: Encryption key derived from the secret key.
  • -iv: Initialization Vector used in the encryption process.

4. API Workflows

4.1. Initiate a Payout (/v3/pay-request)

Step 1: Create the Beneficiary Object

Form a JSON object with the following structure and parameters:

Main Request Parameters:
PARAMETER DATA TYPE DESCRIPTION MIN/MAX VALUE REQUIRED
amount Number Amount to transfer 2-10 Yes
currency String ISO 4217 currency code (e.g., AUD) 3 Yes
order_id String Your unique transaction ID Up to 20 Yes
pay_mode String Payment method (e.g., AUAT) 2-4 Yes
sub_pay_mode String Sub-payment method (e.g., BSB) 2-4 Yes
merchant_id String Your Swipelocal Merchant ID 15-18 Yes
salt String Your Salt (from the dashboard) 18-20 Yes
beneficiary Object Contains beneficiary details - Yes

Beneficiary Object Parameters
PARAMETER NAME DATA TYPE DESCRIPTION MIN/MAX VALUE REQUIRED
bank_acc_no String Beneficiary's bank account number 6-20 Yes
name String Beneficiary's full name Up to 50 Yes
bank_name String Name of the beneficiary’s bank 5-50 Yes
bank_code String Beneficiary bank code (e.g., BSB) 2-20 Yes
mobile Number Beneficiary mobile number (with country code, no +) 8-13 Yes
email String Beneficiary email address 5-50 Yes
country String Beneficiary country 5-50 Yes
address String Beneficiary street address 5-100 Yes
city String Beneficiary city 5-50 Yes
state String Beneficiary state 5-50 Yes
pincode String ZIP or postal code 4-10 Yes

Step 2: Follow the Encryption Steps (3.1) to encrypt this entire JSON object.
Step 3: Send the encrypted payload in a POST request to {baseUrl}/v3/pay-request.

Sample Decrypted Response:

{

"status": "Success",
"data": {
"status": "Accepted",
"status_code": "0000",
"amount": "19.66",
"txn_id": "UA24/3232583M-00165",
"merchant_id": "UM207EHIT23FAH",
"order_id": "6785183",
"remarks": "Request Accepted"
 }

}


4.2. Check Balance (/v3/get-balance)

Step 1: Encrypt the below request:

{

"salt":"9ZRoJDkzqzS6oLg5GgHhP2TamQgb2wbs"

}

Step 2: Create Request Object

{

"mid":"UM*********6LT",
"data":"KdM2XgUzs9OL5CNo8MqJTEpqF8Ymy1VK+lzJdphgu5wdBTuYumSTnL5rEP9ux+gX"

}

Step 3: Generate a SHA-256 hash by appending your Salt Key to the plaintext string of the above object and hashing it. Add this hash to the request.

Example :

{

"mid": “is3Y68VJFS81R”,
"txn_id": “UA25032810414231” ,
"hash": "48DJ29DJSTFD69FJDSJS49DJSJW93JFNFNS84HBSI4NQNFRFE47S":

}

Step 4: Follow the Encryption Steps (3.1) to encrypt the complete request (including the hash).
Step 5: Send the encrypted payload in a POST request to {baseUrl}/v3/get-balance.

Sample Decrypted Response:

{

"status": "Success",
"remarks": "Success",
"data": {
"currencyCode": "AUD",
"amount": "980.00",
"hash": "57043747064DB8C0B3EB9BE387FC894E57B6C87BB20D9F8386E84S389FC3825"
}

}


4.3. Check Transaction Status (/v3/get-status)

Step 1: Create Request Object

{

"salt": "YOUR_SALT_KEY",
"txn_id": "SWIPELOCAL_TRANSACTION_ID_TO_QUERY"

}

Step 2: Follow the Encryption Steps (3.1) to encrypt this object.
Step 3: Send the encrypted payload in a POST request to {baseUrl}/v3/get-status.

Sample Decrypted Response:

{

"status": "Failed",
"status_code": "4444",
"amount": "746",
"txn_id": "LA25032712562246IB77",
"order_id": "ORD-250327125550-66ODIA",
"remarks": "Failed at Bank End",
"hash": "084813543C067BAB36CCCDAD32C23BGC08FD4BCAA54BB07A0377585C3CBE200C5"

}

5. Appendix

5.1. Payment Methods (pay_mode & sub_pay_mode)

Currency Method Paymode Subpaymode
AUD BSB AUAT BSB

5.2. API Status Codes

STATUS NAME STATUS CODE REMARKS
Accepted 0000 Request Accepted
Success 1111 Payment Successful
Pending 2222 Payment Under Processing
Rejected 3333 Request Rejected
Failed 4444 Failed at Bank End
Reversed 1010 Payment Reversed