- [email protected]
Suite 1238, Level 1, 241 Adelaide St, Brisbane QLD 4000 Australia
Swipelocal Payin API Integration Guide
1. Introduction & Overview
We provide an in-depth overview of the API, including its purpose, endpoints, authentication methods, data formats, and usage guidelines. You will have a comprehensive understanding of how to integrate and work with the API effectively, enabling you to harness its power for your specific use case.
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://payin.swipelocal.au/
2. Core API Endpoints
| Endpoint | Method | Description |
|---|---|---|
| /v3/pay-request | POST | Initiate a payin to a beneficiary |
| /v3/get-status | POST | Check the status of a specific transaction |
Get Started
Parameters
| PARAMETER NAME | DATA TYPES | DESCRIPTION | MIN/MAX VALUE | REQUIRED |
|---|---|---|---|---|
| amount | NU | Amount to be received from the payer | 3-10 | Yes |
| currency | CH | Currency Code as per ISO 4217 standard | 3 | Yes |
| pay_mode | CH | pay_mode refers to the method used for processing a payment | 2-4 | Yes |
| sub_pay_mode | CH | It specifies the exact method used for the payment | 2-4 | Yes |
| merchant_id | AN | A unique Id shared by Swipelocal | 15-18 | Yes |
| order_id | AN | Merchant unique reference id Hypen & underscore allowed | 2-50 | Yes |
| cust_name | CH | Name of the customer, only in English alphabets | 2-50 | Yes |
| cust_email | Email format | Customer Email | 6-20 | Yes |
| return_url | URL Format | Your return_url | 6-50 | Yes |
| cust_phone | NU | Customer phone number, with county code but without + sign | 8-13 | Yes |
| hash | AN | SHA-256 results in a 64-character hash | 64 | Yes |
| cust_country | CH | Customer country | 3-30 | Yes |
| remarks | AN | Remarks for your reference | 3-50 | No |
3. Encryption Method for Secure Data Transmission
3.1. Generating a Secure Hash SHA-256 Signature
Merchants must generate a Secure Hash value based on the transaction request data. The Payment Serverwill also generate a hash for the transaction response, which is then validated to ensure data integrity.
To generate a Hash, you need to make a request for all the required parameters. For example, if you want to pass the following name-value pairs in your request.
3.2 Prepare a JSON Request with Mandatory Parameters
Below is an example JSON request containing all required parameters:
{
"amount": "10.00",
"currency": "AUD",
"pay_mode": "AUPI",
"sub_pay_mode": "AUPD",
"merchant_id": "UMWWKPMTWZUG2E1",
"order_id": "123-345FD-dfg4567-456",
"cust_name": "PayerName",
"cust_email": "[email protected]",
"cust_phone": "2343414534561",
"cust_country": "UAE",
"return_url": "https://pgtesting.in/callback",
"callback_url": "https://pgtesting.in/callback",
"remarks": "testpayemnt"
}
3.3 Sort the JSON Request
Sort all parameters of the prepared JSON request in ascending order by key.
3.4 Convert JSON to String (Using ~ as a Separator)
Next, convert the sorted JSON into a single string. Use the ~ symbol as a separator between key–value pairs.
Finally, append the Salt Key at the end of the string.
Pre-Hash String Example:
amount=10.00~callback_url=https://pgtesting.in/callback~currency=AUD~cust_country=UAE~c [email protected]~cust_name=Payer Name~cust_phone=2343414534561~merchant_id=UMWWKPMTWZUG2E1~order_id=123- 345FD-dfg4567-456~pay_mode=AUPI~remarks=test payemnt~return_url=https://pgtesting.in/callback~sub_pay_mode=AUPDZRoJDkzqzS6onlkjsnflf aklefkal20
3.5 Generate SHA-256 Hash
Now you will have to call SHA 256 algorithm and pass the parameter string to the same and the SHA will return you the desired result as below
Example of SHA-256 Hash:
4c0cbffeb943a74234ac4e3d9bac3ef8ae4ae2f61e463e538fe3794d74bd79e4
Convert the generated value to uppercase, which will be the final hash:
4C0CBFFEB943A74234AC4E3D9BAC3EF8AE4AE2F61E463E538FE3794D74BD79E4
3.6 Add Hash Parameter to the JSON Request
encrypt_str={"amount": "10.00","currency": "AUD","pay_mode": "AUPI","sub_pay_mode": "AUPD","merchant_id": "UMWWKPMTWZUG2E1","order_id":"123-345FD-dfg4567- 456","cust_name": "Payer Name","cust_email": "[email protected]","cust_phone": "063414534561","cust_country":"UAE","return_url": "https://pgtesting.in/callback","callback_url": "https://pgtesting.in/callback","remarks": "test payemnt","hash":"4C0CBFFEB943A74234AC4E3D9BAC3EF8AE4AE2F61E463E538FE3794D74BD"}
3.7 Encrypt Method: openssl enc -aes-256-cbc
- iv - The first 16 characters of your secret key will serve as the Initialization Vector (IV).
- enc key -Use the first 32 characters of the secret key for the encryption key, skipping the initial 16 characters.
You will get encrypted data, which you will then pass as the request data.
4. Pay Request
End Point: /v3/pay-request
Method: POST
Description: Create a new payment request
Request with encrypted data
{
"mid": "iA****0kvUHxazo",
"data":
"FEZQmxMXriEfA50gP8ntBqxej+QMnBFbeH8fzMSPTr0trrLadD5iKGHZqFCh4T1FG+TG0FmE+iol2oX461EET7DjLtW3N0u/cVt7cA202PKYmVNTH5ndxs7OcFJzcYrLV08V FlX6VVs2e7/4+WLxZRPEZpjypufaCSJJtdTVePIIH2xjIH4zspWsavFq9tq9nlZZtUOuEovvjvADVdWHq8KQY8p3/YWo5jFlG1oVZkUfwsdLyNGPxpD2IiZ0Xsj9fh8Q1Rfozgk
Dqx/OWwLzreGbxM0FT9l5/T0YiP3NFHAHY3nCVq6JiRflgu5Opo7PYAaT5SEgASa+iV1YquDzA3PHE5e2DfSusxVmulU5VUlz9+HPIZ30xV7ZKNlH7vyda4RvcPLdYWsItrN3XM
QZpUYvmIIZLt5bMtvdS3Do4WZgW/V2NFnR4IsHk7M6Rn+/i3+P1qht0Ept3l1S/K/tofLkxLGMJtERUQXI0jlfkqjDwP "
}
Response
{
"status": "Success",
"remarks": "Success",
"data":
"fMrCfhtikCMjS5Y3+HyHRgc3mt4JHracb2cJJlYypxjguhK88bJsm07F5TmLRvzXpLZXRXqvDSyV99phyv7cj7ilzeDjhH1VLMODY24IHJj8+aZj1e6MKVaWTJ4x08 UKlF6RfRcTftgO9vl0ut/0dmwc1mJR5iT9GTtToiUHf/kQBIiApT1gehntiA9Exbqz9QpyS+7ZsXZouKkK4btWUE1LW6izn0Sv1RhPbH2M0PucMVlBwC3rCUuglS/qF l2Xtq6HS7NO3+ZJ5hXnXbMKNN7FHdMDrsBh4bLfGSXsdkQtIB3RAfb340e/BzY9X3b30NBPoRT90hIpWyXpfFQuhnrDfQWdQc8Jg4BzYTZJtN6n9f3BlV0bGUT VPh+2D25+qZzOwmbqyGywebMP/Byx7Rr92HlPS3jat+Vf7C3pR05qGI1feHgTQk/2QC+gq6LuP4DI9GXGqhUH1MnHt8TV7AvKcIWVSNJswheMIl3IWrbkRUHV GtcjvEIYru42b7P4atFtcNKij/LDE8A1E3/qkUAtQEWQ8UVMLVrjZGA3REAfyVGLGH4HlGSXQKBa9VevyavMcxvIXXkApIuq05SnLoT6UIZr36LCxG7jzH+D1EI4W tXxiVYbSYDiNWNGcQJy"
}
5. Decryption Method for Secure Data Transmission
Now, use the AES-256-CBC decryption method to decrypt the data with the extracted IV and encryption key.
Example using OpenSSL:
openssl enc -d -aes-256-cbc -in encrypted_data.txt -out decrypted_data.txt -K-IV
Explanation:
- d: Indicates decryption.
- aes-256-cbc: The AES algorithm in CBC mode.
- in encrypted_data.txt: The file containing the encrypted data.
- out decrypted_data.txt: The output file for the decrypted data.
- K: The encryption key derived from the secret key.
- iv: The Initialization Vector used in the encryption process.
5.1 After Decryption Response
After decryption, the data will be in a readable format (like JSON) and will contain the original transaction details, as shown below:
{
"status": "Pending",
"status_code": "2222",
"amount": "119",
"txn_id": "DI****************49",
"order_id": "TEST-001",
"remarks": "Payment Under Processing",
"redirect_url":
"https://https://payin.swipelocal.au/7894huf8923q9j2smd92js05nwndjw3FHF”,
"hash": "2209B546968652AED68A599E5CB392B68E429222FB2ACC19D58E62AAF0186046"
}
Now, you can use redirect_url to complete the payment.
6. Get Status
End Point: /v3/get-status
Method: POST
Description: get the status of the transaction.
6.1 Request body
{
"mid": “is3Y68VJFS81R”,
"txn_id": “UA25032810414231”
}
6.2 Generate the hash using the above shared request body by appending salt at the end of the plain text (Refer Generating a Secure Hash SHA-256 Signature).
{
"mid": “is3Y68VJFS81R”,
"txn_id": “UA25032810414231” ,
"hash": "48DJ29DJSTFD69FJDSJS49DJSJW93JFNFNS84HBSI4NQNFRFE47S":
}
6.3 Encrypt the above request body and you will get encrypted data, which you will then pass as the request data.
Encrypted Request Body
{
"mid": " is3Y68VJFS81R ",
"data":"4agAqQqdPsHh9zcguhS+2bAqRINNpOJUvrGWSFywfSAUt3yYw40ntTmMo5aGcXCOOO4mBVrN/C2dZbSo9OF1qm86ZmFm25dhYA6i6zsMULS1qNgR7vMLj KO0RHZW0QO62/67jPX1QicSA4inhmb9U+JonaaRKZmK5974pZ9VHec8GYn55ZRVMYITYY oMv6"
}
Encrypted Response Body
{
"mid": " is3Y68VJFS81R ",
"data":"4agAqQqdPsHh9zcguhS+2bAqRINNpOJUvrGWSFywfSDwTC6oQAhs6DpsiQx65FFObnNrSK4nfA02I81FnHbhnuIj25az6i9llr9haKqvVq35/XWzAWm8 K2nGZLZtueiDfKK54ltJwhLcVLjmPL2rg0V2piIsz2/JeWJHR3a+AFq3dUAn7Dvqf/MxC0j+CBDM"
}
6.4 Decrypt the response, after decryption, the data will be in a JSON format and will contain the transaction details
{
"status": "Failed",
"status_code": "4444",
"amount": "746",
"txn_id": " UA25032810414231",
"order_id": "ORD-250327125550-65GDIA",
"remarks": "Failed at Bank End",
"rrn": "",
"hash": "084B13431C5C7BAB36CECDAD32C2319C095D4BCA34BB07A0377555C3C9E200C5"
}
Note : Callback and get-status response are same.
7. Appendix
Paymode and Subpaymode
| Currency | Method | Paymode | Subpaymode |
|---|---|---|---|
| AUD | PayID | AUPI | AUPD |
API Status
| STATUS NAME | STATUS CODE | REMARKS |
|---|---|---|
| Success | 1111 | Payment Successful |
| Pending | 2222 | Payment Under Processing |
| Rejected | 3333 | Request Rejected |
| Failed | 4444 | Failed at Bank End |
| Cancelled | 5555 | Payment not completed by the payer |
Webhook Configuration
You can get the webhook on Callback URL as event notifications.
You can configure webhook URL from the merchant dashboard panel:
Dashboard-->Settings--> Profiles--> Edit --> Payin Callback URL
You can get in touch with Swipelocal team to configure the webhook URLs.