Introduction

Welcome to the Wipays API! You can use our API to receive payments from your customers. You will be able to create payment links, and receive payment notifications.

This API documentation is a part of Wipays. Feel free to contact us for any questions or feedback.

Authentication

To authorize, add the field public_key to the body of your request:

curl -X POST https://{{DOMAIN}}/endpoint \
-H "Content-Type: application/json" \
-d '{
  "public_key": "your_api_key"
}'

You will need 2 keys to use Wipays API: public_key and secret_key. You can receive both API keys from your support manager.

public_key is used to authenticate your requests to the API. You should include it in the body of your request.

secret_key is used to generate and verify signatures for Instant Payment Notification (IPN).

Initiate Payment

To initiate a payment, send a POST request to the following endpoint: Fields are sorted in alphabetical order.

curl -X POST https://{{DOMAIN}}/payment/initiate \
-H "Content-Type: application/json" \
-d '{
  "public_key": "your_api_key",
  "amount": "",
  "billing_info": {
       "address_one": "",
       "address_two": "",
       "area": "",
       "city": "",
       "sub_city": "",
       "state": "",
       "postcode": "",
       "country": "",
       "others": "",
  },
  "cancel_url": "",
  "currency": "USD",
  "customer": {
      "first_name": "",
      "last_name": "",
      "email": "",
      "mobile": "",
  },
  "details": "",
  "identifier": "",
  "ipn_url": "",
  "shipping_info": {
       "address_one": "",
       "address_two": "",
       "area": "",
       "city": "",
       "sub_city": "",
       "state": "",
       "postcode": "",
       "country": "",
       "others": "",
  },
  "site_name": "",
  "site_logo": "",
  "success_url": "",
}'

This endpoint initiates a payment. The response will contain a payment link that you can redirect your customer to.

HTTP Request

POST http://{{DOMAIN}}/payment/initiate

Query Parameters

Parameter	Required	Description	Example
public_key	true	Your API key.	"your_api_key"
amount	true	The amount to be paid.	100.00 , 100
cancel_url	true	The URL to redirect the customer to if the payment is canceled.	"https://yoursomain.com/cancel"
currency	true	The currency of the payment	"USD", "EUR", "CAD"
customer	true	The customer's information. (see Customer parameters)	See Customer parameters
details	true	The details of the payment. Max 255 symbols.	"Payment for order #123"
identifier	true	A unique identifier for the payment. Preferrably uuid. Max 255 symbols.	YOUR_UNIQUE_IDENTIFIER
ipn_url	true	The URL to send payment notifications to.	"https://yoursomain.com/ipn"
site_name	true	The name of your website.	"Your Website"
success_url	true	The URL to redirect the customer to after a successful payment.	"https://yoursomain.com/success"
billing_info	false	The billing information of the customer.	See Billing Info parameters
shipping_info	false	The shipping information of the customer.	See Shipping Info parameters
site_logo	false	The URL to your website's logo.	"https://yoursomain.com/logo.png"

Customer Parameters

Parameter	Required	Description	Example
first_name	true	The customer's first name.	"John"
last_name	true	The customer's last name.	"Doe"
email	true	The customer's email.	"[email protected]"
mobile	true	The customer's mobile number.	"+1234567890"

Billing Info Parameters

Parameter	Required	Description
address_one	false	The first line of the customer's address.
address_two	false	The second line of the customer's address.
area	false	The area of the customer's address.
city	false	The city of the customer's address.
sub_city	false	The sub-city of the customer's address.
state	false	The state of the customer's address.
postcode	false	The postcode of the customer's address.
country	false	The country of the customer's address.
others	false	Any other information about the customer's address.

Shipping Info Parameters

Parameter	Required	Description
address_one	false	The first line of the customer's address.
address_two	false	The second line of the customer's address.
area	false	The area of the customer's address.
city	false	The city of the customer's address.
sub_city	false	The sub-city of the customer's address.
state	false	The state of the customer's address.
postcode	false	The postcode of the customer's address.
country	false	The country of the customer's address.
others	false	Any other information about the customer's address.

Response

{
  "status": "success",
  "message": "Payment initiated successfully",
  "redirect_url": "https://wipays.com/payment/checkout?payment_trx=UNIQUE_PAYMENT_ID"
}

Parameter	Description	Example
status	The status of the request.	"success"
message	The message of the request.	"Payment initiated successfully"
redirect_url	The payment URL to redirect the customer to.	"https://wipays.com/payment/checkout?payment_trx=UNIQUE_PAYMENT_ID"

IPN (Instant Payment Notification)

Wipays sends payment notifications to the IPN URL you provide in the payment initiation request. The IPN will contain the payment details.

IPN Parameters

Parameter	Description	Example
identifier	The unique identifier of the payment that you have sent when initiating the payment	"YOUR_UNIQUE_IDENTIFIER"
status	Status of the event the notification is about	"success"
signature	Hash for the authentication. Uppercase of sha256 of `{identifier}{timestamp}` signed with your secret_key
timestamp	The timestamp when the IPN was sent. Use it to generate and check signature	1631533200
data	The payment details.	See Payment Details parameters

Signature Generation

To generate the signature, you should hash the concatenation of the identifier and timestamp with your secret_key using sha256 and convert it to uppercase. See the code examples. PHP example is the "source of truth" for the signature generation

$signature = strtoupper(hash_hmac('sha256', $identifier.$timestamp, $secret_key));

const signature = crypto.createHmac('sha256', secret_key).update(`${identifier}${timestamp}`).digest('hex').toUpperCase();

IPN types

Checkout - type: "checkout"
Chargeback Initiated - type: "chargeback_initiated"
Chargeback Resolved - type: "chargeback_resolved"

Checkout IPN Data

Parameter	Description	Example
trx	The internal unique identifier of the payment. DO NOT use this to generate and check signature.	"UNIQUE_PAYMENT_ID"
amount	The amount of the payment or chargeback related to the IPN	100.00
currency	The currency of the payment or chargeback related to the IPN	"USD"
type	The type of the IPN.	"checkout"
timestamp	The timestamp of the payment or chargeback related to the IPN. DO NOT use this to generate and check signature	"2021-04-05 00:00:00"

Chargeback Initiated IPN Data

Parameter	Description	Example
trx	The internal unique identifier of the payment. DO NOT use this to generate and check signature.	"UNIQUE_PAYMENT_ID"
amount	The amount of the chargeback	100.00
type	The type of the IPN.	"chargeback_initiated"
initiated_at	The timestamp of the chargeback initiation. DO NOT use this to generate and check signature	"2021-04-05 00:00:00"
message	The message of the chargeback.	"Chargeback initiated on this transaction"
timestamp	The timestamp of the related payment URL creation. DO NOT use this to generate and check signature	"2021-04-05 00:00:00"
currency	The currency of the chargeback	"USD"

Chargeback Resolved IPN Data

Parameter	Description	Example
trx	The internal unique identifier of the payment. DO NOT use this to generate and check signature.	"UNIQUE_PAYMENT_ID"
amount	The amount of the chargeback	100.00
type	The type of the IPN.	"chargeback_resolved"
in_favor_of	The party in favor of the chargeback.	"client", "merchant"
timestamp	The timestamp of the chargeback resolution. DO NOT use this to generate and check signature	"2021-04-05 00:00:00"
currency	The currency of the chargeback	"USD"