This API is used to place an order. Depending on your use case you can decide whether to get the details of the gift cards
synchronously or asynchronously.
Mandatory parameters must be passed in the request to get the correct response. The card details response received must
be saved in API Client’s database in an encrypted form. Whenever the
details must be retrieved it has to be taken from the local database, rather than calling the server.
This API supports synchronous and asynchronous mode using synconly parameter:
• If request is processed asynchronously then synconly attribute should be false, HTTP status code is 202(Accepted) and real
-time status of order will be available on Status API.
• If request is processed synchronously, then syncOnly attribute should be true, and HTTP status code would be
201(Created). GC details will be returned in the response
Note – On billing address, email and telephone is mandatory, irrespective of delivery mode.
Method: POST
URL/Path: baseurl/rest/v3/orders
E.g.: extapi12.budgetree .in/rest/v3/orders
Request Header:
| Content-Type | application/json |
| Accept | */* |
{
"address": {
"salutation": "Mr.",
"firstname": "Jhon",
"lastname": "Deo",
"email": "jhon.deo@gmail.com",
"telephone": "+919999999999",
"line1": "address details1",
"line2": "address details 2",
"city": "bangalore",
"region": "Karnataka",
"country": "IN",
"postcode": "560076",
"billToThis": true,
"gstn": "1234567890",
"code": "123"
},
"billing": {
"salutation": "Mr.",
"firstname": "Jhon",
"lastname": "Deo",
"email": "jhon.deo@gmail.com",
"telephone": "+919999999999",
"line1": "address details1",
"line2": "address details 2",
"city": "bangalore",
"region": "Karnataka",
"country": "IN",
"postcode": "560076",
"company": "Accenture",
"gstn": "123456",
"code": "abc"
},
"isConsolidated": false,
}
Note: “syncOnly” value will always be false for payout transactions and “orderType” value will always be “PAYOUT”.
Refer below payload for UPI transaction:
{
"payout": {
"type": "UPI",
"vpa": "test@okhdfc",
"email": "test@gmail.com",
"name": "abc test",
"telephone": "+918888888888",
"transactionType": "UPI"
}
}
Refer below payout for beneficiary id:
{
"payout": {
"id": "62e96ca39b6400001e00330d",
"transactionType": "IMPS"
}
}
| Field Name | Mandatory | Data Type | Length | Description | Example |
|---|---|---|---|---|---|
| address | object | Shipping Address. This can be optional if the default address is configured for the customer | |||
|
no | string | max 50 | Salutation (Shipping) | Mr. |
|
yes | string | min 2 and max 100 characters | First name. Any regional language alphabets are allowed | Jhon |
|
|
Mandatory/Optional based on the delivery mode | Alphanumeric | min 3 and max 250 characters | Shipping E-mail address, this is required if deliveryMode is Email.
Either Shipping E-mail address or Shipping Telephone Number is required if delivery mode is API Both Shipping E-mail address and telephone number is required if delivery mode is ANY. |
jhon.deo@gmail.com |
|
Mandatory/Optional based on the delivery mode | string | E164 format | Shipping Telephone number in (E164) format. This is required if deliveryMode is SMS.
Either Shipping E-mail address or Shipping Telephone Number is required if delivery mode is API. Both Shipping E-mail address and telephone number is required if delivery mode is ANY. This has to be a valid mobile number in E164 format. |
+919999999999
(This is a dummy phone number mentioned for example and must not be used to place order) |
|
no | Alphanumeric | min 2 and max 100 characters | This is required for physical gift card | line 1 |
|
no | Alphanumeric | min 2 and max 100 characters | line 2 | |
|
no | Alphabets | min 2 and max 50 characters | This is required for physical gift cards | city |
|
no | Alphabets | min 2 and max 50 characters | Shipping State, this is required for physical gift cards | karnataka |
|
yes | Alphabets | min 2 and max 2 characters | Shipping country alphabetic code | IN |
|
yes | numeric | Min 3 and max 20 characters | Valid sender Postcode or Pincode | |
|
no | string | Max 85 | GST number of the company provided in the address object | 1234567890 |
|
no | string | Max 100 | Company code in the address object | 123 |
|
no | boolean | True: Shipping address is same as Billing Address | true/false | |
| billing | object | This is considered only if address.billToThis is false.
This is optional if user profile address is provisioned at Qwikcilver. |
|||
|
no | string | max 50 | Salutation (Billing) | Mr. |
|
yes | string | min 2 and max 100 characters | First name. Any regional language alphabets are allowed | Jhon |
|
no | string | min 2 and max 100 characters | Last name. Any regional language alphabets are allowed | Deo |
|
|
Mandatory/Optional based on the delivery mode | Alphanumeric | min 6 and max 250 characters | Billing E-mail address.
Either Billing E-mail address or Billing Telephone Number is required if delivery mode is API. Both Billing E-mail address and telephone number is required if delivery mode is ANY. This has to be a valid mobile number in E164 format. |
jhon.deo@gmail.com |
|
Mandatory/Optional based on the delivery mode | string | E164 Format | Billing Telephone number in (E164) format.
Either Billing E-mail address or Billing Telephone Number is required if delivery mode is API. Both Billing E-mail address and telephone number is required if delivery mode is ANY. This has to be a valid mobile number in E164 format. |
+919999999999
(This is a dummy phone number mentioned for example and must not be used to place order) |
|
yes | Alphanumeric | min 2 and max 100 characters | This is required for physical gift card | line 1 |
|
no | Alphanumeric | min 2 and max 100 characters | line 2 | |
|
yes | Alphabets | min 2 and max 50 characters | This is required for physical gift cards | city |
|
yes | Alphabets | min 2 and max 50 characters | Billing State, This is required for physical gift cards | karnataka |
|
yes | Alphabets | min 2 and max 2 characters | Billing country alphabetic code | IN |
|
yes | numeric | Min 3 and max 20 characters | Valid sender Postcode or Pincode | |
|
no | string | max 50 | Corporate Name | Accenture |
|
no | string | Max 85 | GST number of the company provided in the billing object | 123456 |
|
no | string | Max 100 | Company code in the billing object | abc |
| isConsolidated | no | boolean | True/False | Set to TRUE when you want to send several individual items from an order in a single shipment. Internal field |
false |
| payments | array | Payment information | |||
| Object | |||||
|
yes | string | NA – Predefined values | Available codes are SVC and evocherredemption_standard.
SVC – Credit limit assigned at the platform level. Refer to the note below for payment code “evocherredemption_standard” |
svc |
|
yes | numeric | NA | Payment Amount for the order. This value is multiplier of Price*Quantity for Product | 1000 |
|
yes | string | Max 55 | Unique number assigned to a purchase order that covers transaction details. Note: Set to yes for purchaseorder payment |
johndeo01 |
|
no | Datetime | Format :yyyy-mm-dd H:m:s | Date on which any PurchaseOrder is issued | 2022-06-29 6:11:50 |
|
no | string | Max 140 | Mode of payment | ANY |
| products | Object | ||||
| object | |||||
|
yes | Alphanumeric | Predefined values | Valid SKU from (Product API) | budgetree |
|
yes | numeric | NA | Gift card activation amount | 1000 |
|
yes | numeric | Predefined values | Gift card quantity | 1 |
|
yes | numeric | 3 digits | (Currency numeric code) | 356 |
|
Object | ||||
| id | yes | string | Beneficiary id | 62e96ca39b6400001e00330d | |
| type | yes | string | Min 3 and max 15 | Account type identifier Accepted values are BANK_ACCOUNT, UPI | BANK_ACCOUNT |
NOTE: Refer the below payment object if the payment code is “evocherredemption_standard”
{
"payments": [
{
"code": "evocherredemption_standard",
"amount": 10000,
"card_number": "1234567890123456",
"card_pin": "123456"
}
]
}
| Field Name | Mandatory | Data Type | Length | Description | Example |
|---|---|---|---|---|---|
| payments | array | ||||
| Object | |||||
|
yes | string | NA | Payment Code. Predefined value is “evocherredemption_standard” | evocherredemption_standard |
|
yes | numeric | NA | Payment amount for the order | 10000 |
|
yes | string | NA | Card Number for redemption | 1234567890123456 |
|
yes | string | NA | Card PIN associated with the Card Number | 123456 |
Sample Response
Sample Response 202
{
"status": "PROCESSING",
"orderId": "5100056000",
"refno": "000000000017",
"currency": {
"code": "INR",
"numericCode": "356",
"symbol": "₹"
},
"payments": [
{
"code": "svc"
}
]
}
Sample Response 201
{
"status": "COMPLETE",
"orderId": "333335778",
"refno": "1617632932591",
"cancel": {
"allowed": true,
"allowedWithIn": "2"
},
"currency": {
"code": "INR",
"numericCode": "356",
"symbol": "INR"
},
"payments": [
{
"code": "purchaseorder"
}
],
"cards": [
{
"sku": "ACTVPRD",
"productName": "Active Product Default W00h00",
"labels": {
"cardNumber": "Gift Card Number",
"cardPin": "Card PIN",
"activationCode": "Activation Code",
"validity": "Validity"
},
"cardNumber": "9000002223896157184",
"cardPin": "320467",
"activationCode": null,
"barcode": "",
"activationUrl": null,
"formats": [
{
"key": "QCGTINBARCODE-32",
"value": "1234567899000002223896157184"
}
],
"amount": "100.00",
"validity": "2022-04-04T18:30:00+00:00",
"cardId": 2637,
"recipientDetails": {
"salutation": "Mr.",
"name": "Neha Kumari",
"firstname": "Neha",
"lastname": "Kumari",
"email": "neha.kumari@qwikcilver.com",
"mobileNumber": "+917903762668",
"status": "",
"failureReason": ""
"delivery": {
"mode": "ANY",
"status": {
"sms": {
"status": "NA",
"reason": "NA"
},
"email": {
"status": "NA",
"reason": "NA"
}
}
}
},
"theme": ""
}
],
"products": {
"ACTVPRD": {
"sku": "ACTVPRD",
"name": "Active Product Default W00h00",
"balanceEnquiryInstruction": null,
"specialInstruction": {
"label": "Add to budgetree ",
"url": "https://www.budgetree .in/account"
},
"images": {
"thumbnail": "",
"mobile": "",
"base": "",
"small": "http://devcdn.giftbig.com/uat/product/sku/d/small_image/4_microsite.png"
},
"cardBehaviour": "QC"
}
},
"additionalTxnFields": []
}
Sample Response 201 (If “cardNumber” is passed as a parameter in the request.)
NOTE: When card is successfully activated.
{
"status": "COMPLETE",
"orderId": "9300003566",
"refno": "Ref-Num-20210305170631515",
"cancel": {
"allowed": true,
"allowedWithIn": "15"
},
"currency": {
"code": "INR",
"numericCode": "356",
"symbol": "₹"
},
"payments": [
{
"code": "purchaseorder"
}
]
}
Sample Response 201(If “cardNumber” is passed as a parameter in the request)
NOTE: When card activation is failed.
{
"status": "PROCESSING",
"orderId": "9300003968",
"refno": "Ref-Num-2021030517063152409",
"cancel": {
"allowed": true,
"allowedWithIn": 15
},
"currency": {
"code": "INR",
"numericCode": "356",
"symbol": "₹"
},
"payments": [
{
"code": "purchaseorder"
}
]
}
Sample Response 400
{
"message": "Duplicate reference number provided",
"code": 5313,
"messages": [],
"additionalTxnFields": []
}
Response Parameters
1. Success
| Field Name | Mandatory | Data Type | Description | Example |
| status | no | string | This indicates the current status of the order | PROCESSING |
| orderId | no | string | Budgetree reference number | 1000000001 |
| refno | no | string | Client reference number | 1000000001 |
| payments | array | |||
| Object | ||||
2. Failure
| Field Name | Mandatory | Data Type | Description | Example |
|---|---|---|---|---|
| code | no | number | Error Code | 5313 |
| message | no | string | Error Message | Duplicate reference number provided |
| messages | no | array | ||
| additionalTxnFields | yes | array | Additional Transaction details |
HTTP Codes
| Status Code | Message | Description |
|---|---|---|
| 201 | Created | This indicates that the order has been successfully created, and the gift card is activated. |
| 202 | Accepted | This indicates that Budgetree has accepted the order, and the gift card is going to be activated asynchronously. Real-time status of the order is available on the Status API. |
| 400 | Bad Request | This indicates that request validations have failed. |
| 401 | Unauthorized | This indicates that OAuth authorization failed to validate. |
| 403 | Forbidden | This indicates that API access has been revoked or there are insufficient permissions. |
| 500 | Internal Server Error | This indicates that an error occurred on budgetree . |
Error Response Codes
| Status Code | Description |
|---|---|
| 400 | Request data is invalid. |
| 5035 | Payment service is not available. |
| 5036 | Payment amount does not match the uploaded value (e.g., 600 with the required value of 500). |
| 5037 | Payment service model is not available. |
| 5038 | Payment service exceeds limitations. |
| 5046 | Customer is not available. |
| 5080 | Payment for Amazon is restricted. |
| 5103 | Card number is required for reloading the Budgetree product. |
| 5305 | Requested store is inactive. |
| 5307 | 500 Denomination is not available for product SKU: budgetree . Please choose a different denomination. |
| 5308 | Unable to process your order as some of the products are restricted for your account. |
| 5310 | The SKU budgetree you are looking for is not available. |
| 5311 | Invalid delivery mode EMAIL. |
| 5312 | Default billing address is not configured. |
| 5313 | Duplicate reference number provided. |
| 5315 | Product misconfiguration. |
| 5318 | Denomination is not available. |
| 5321 | Order cannot be processed. |
| 5326 | Combination of product types Digital & Physical is not supported. |
| 5327 | Apologies, payment for your Order has failed. Please place a fresh order. |
| 5333 | Order cannot be processed as the transaction has been refunded. |
| 5334 | Delivery Mode is not allowed with physical product. |
| 5335 | Invalid order type invalidType. |
| 5338 | Amount exceeds the maximum allowed order value: 1000 (order value 1500, order refno: 0000000000175341). Edit address is not allowed, but the request has address info. |
| 5342 | Default shipping address is not configured. |
| 5343 | Invalid external login. |
| 5344 | External login is not required. |
| 5348 | Payment method payu cannot be combined with another payment. |
| 5349 | PO number should be the same for all payments. |
| 6000 | Activation failed. |
| 6050 | Order cannot be processed. |
| 6051 | OTP is required. |
| 6052 | Invalid OTP. |
| 6053 | Could not process your request. Please try again later. |
| 6054 | Invalid email delivery id. |
| 6057 | This order does not support consolidated delivery. |
| 6058 | This order does not support multiple currencies. |
| 6059 | This currency is not allowed. |
| 6063 | Order cannot be placed due to insufficient balance. |
Last updated on: