🧾Orders

API's to manage Orders.

Production URL: https://orders-v1-api-rdqehkur6a-ey.a.run.app

Create Order

Please Note: If you want to pre-populate user data for the Stripe Onramp payment feature - Please ensure to add the customerInformation object data.

Create a new order.

POST/orders

Header parameters

Body

application/json

typestring

Order type e.g. "payment", "deposit".

namestring

Name of the order.

descriptionstring

Description of the order.

orderNumber*string

Unique order number.

amount*number

Total amount of the order. Amount is optional for 'deposit' orders.

emailstring

Email of the customer making the order.

notifyUrlstring

URL to notify after order is completed.

returnUrlstring

URL to redirect to after order is completed.

customerInformationobject

Optional customer information for the order.

Response

200400401500

Order successfully created.

Body

application/json

messagestring

A message indicating the result of the operation.

dataobject

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/orders', {
    method: 'POST',
    headers: {
      "x-api-key": "text",
      "x-api-hash": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "orderNumber": "text",
      "amount": 1,
      "customerInformation": {
        "dob": {},
        "address": {}
      }
    }),
});
const data = await response.json();

Response

200

{
  "message": "text",
  "data": {
    "orderId": "text",
    "paymentUrl": "text",
    "paymentDeepLinkUrl": "text",
    "status": "new",
    "alreadyExists": true
  }
}

Order Notify Url (Webhook)

WARNING: Ensure that your system accepts payments ONLY when the status of the notifyUrl request is "success".

Order Completed Notify Url

POST https://your-notify-url

Request Body

Name	Type	Description
orderId*	string	TygaPay Order Id.
orderNumber*	string	Unique Order Number .
status*	string	Status of the order upon completion: success: Payment has been successfully processed. expired: The order has expired. cancelled: The order has been cancelled.
date*	string	Order complettion date. i.e 2024-01-07T19:05:30.175Z
amount	number	The paid amount. Amount will only be present if the status is equal to success.
currency	string	i.e USDT, KRU etc Currency will only be present if the status is equal to success.
txId	String	The payment TygaPay txId. TxID will only be present if the status is equal to success.

Order Redirect Url

When an order receives a final outcome, the Payment Gateway will redirect to the specified redirect URL. The redirect URL will have the following parameters appended: ?orderId=[ORDER_ID]&orderNumber=[ORDER_NUMBER]&status=[STATUS]

i.e https://your-redirect-url?orderId=004Qs494RxpEMFYUyXBz&orderNumber=323421&status=success

Fields	Description
ORDER_ID	The TygaPay Order Id
ORDER_NUMBER	The orderNumber supplied in the creation of the order.
STATUS	Status of the order upon completion: success: Payment has been successfully processed. expired: The order has expired. cancelled: The order has been cancelled.

Note: TygaPay will accommodate the specific format required for your redirect URL.

Get Order

Retrieves an order by Id.

GET/orders

Path parameters

orderId*string

Id of the order to retrieve.

Header parameters

Response

200401404500

Order successfully retrieved.

Body

application/json

messagestring

A message indicating the result of the operation.

dataobject

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/orders', {
    method: 'GET',
    headers: {
      "x-api-key": "text",
      "x-api-hash": "text"
    },
});
const data = await response.json();

Response

200

{
  "message": "text",
  "data": {
    "id": "text",
    "orderNumber": "text",
    "name": "text",
    "description": "text",
    "amount": 1,
    "amountPaid": 1,
    "amountDue": 1,
    "status": "new",
    "state": "pending",
    "email": "text",
    "notifyUrl": "text",
    "returnUrl": "text",
    "createdDate": "text",
    "modifiedDate": "text"
  }
}

Cancel Order

Cancels an order by Id.

PUT/orders/:orderId/cancel

Path parameters

orderId*string

Id of the order to cancel.

Header parameters

Response

200400401404500

Order successfully canceled.

Body

application/json

messagestring

A message indicating the result of the operation.

dataobject

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/orders/:orderId/cancel', {
    method: 'PUT',
    headers: {
      "x-api-key": "text",
      "x-api-hash": "text"
    },
});
const data = await response.json();

Response

200

{
  "message": "text",
  "data": {
    "orderId": "text",
    "status": "new"
  }
}

Refund Order to TygaPay Account

Refunds an order by Id.

POST/orders/:orderId/refund

Header parameters

Body

application/json

tygaUserId*string

Name of the order.

notifyUrl*string

Description of the order.

Response

200400401404500

Order successfully refunded.

Body

application/json

messagestring

A message indicating the result of the operation.

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/orders/:orderId/refund', {
    method: 'POST',
    headers: {
      "x-api-key": "text",
      "x-api-hash": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "tygaUserId": "text",
      "notifyUrl": "text"
    }),
});
const data = await response.json();

Response

200

{
  "message": "text"
}

Refund Order to Crypto Address

• To process a refund to a cryptocurrency address, an OTP (One-Time Password) is necessary. Please reach out to [e-mail] to set up the Tenant Admin account that will receive these OTPs.

Send a refund OTP to the tenant admin's account.

POST/orders/:orderId/refund/crypto/otp

Path parameters

orderId*string

The unique identifier of the order for which the refund is to be processed.

Header parameters

Response

200400401404500

Order Refund OTP has been sent successfully.

Body

application/json

messagestring

A message indicating the result of the operation.

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/orders/:orderId/refund/crypto/otp', {
    method: 'POST',
    headers: {
      "x-api-key": "text",
      "x-api-hash": "text"
    },
});
const data = await response.json();

Response

200

{
  "message": "text"
}

Process a cryptocurrency refund for an order.

POST/orders/:orderId/refund/crypto

Path parameters

orderId*string

The unique identifier of the order for which the refund is to be processed.

Header parameters

Body

application/json

address*string

Crypto address to which the refund will be sent.

network*string

Blockchain network used for the refund. e.g. 'BSC', 'MATIC', 'TRON'.

token*string

Type of cryptocurrency token to be refunded. e.g. 'USDT'.

thirdPartyIdstring

An identifier for the third-party service, if applicable.

otp*string

One-time password for transaction verification.

notifyUrl*string

URL to notify upon the final status of the refund process.

Response

200400401404500

Successfully initiated the refund request.

Body

application/json

messagestring

A message indicating the result of the operation.

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/orders/:orderId/refund/crypto', {
    method: 'POST',
    headers: {
      "x-api-key": "text",
      "x-api-hash": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "address": "text",
      "network": "text",
      "token": "text",
      "otp": "text",
      "notifyUrl": "text"
    }),
});
const data = await response.json();

Response

200

{
  "message": "text"
}

Refund NotifyUrl Request (Webhook)

POST https://your-refund-notify-url

Request Body

Name	Type	Description
type*	string	order_refund | order_refund_crypto
orderId*	string	TygaPay Order Id.
orderNumber*	string	Unique Order Number .
status*	string	Status of the order refund upon completion: refunded: Order has been refunded successfully.
date*	string	Order complettion date. i.e 2024-01-07T19:05:30.175Z
amount*	number	The refunded amount.
currency*	string	The refunded currency. i.e USDT
txId*	string	The payment TygaPay txId.
thirdPartyId	string	The specified thirdPartyId is used to initiate the refund request.
address	string	The address to which the refunded amount was sent. This address is provided when the type is order_refund_crypto.
token	string	The token, such as USDT, that has been transferred to the blockchain address.
network	string	The network used to transmit the token.
txHash	string	The blockchain transaction ID, which can be used to verify the legitimacy of the transfer.