Today we will learn how we can use Smile & Pay to receive an instant Ecocash, Innbucks, O'mari or Smile Cash payment and automatically create and send a ZIMRA Fiscal Invoice using a single Panier API call 💪.
First you need to have a Panier account that has been setup with ZIMRA Fiscalisation. If you don't have one, please follow this tutorial.
Setup Smile & Pay Account
- Register a Smile Cash account here
- Once you have gotten your account approved, go to the API Keys section
- Next, we go to the Payment Methods page to select who bearers the transaction cost for each payment method and then click the Save Configurations
- Next, click the Generate API Key button and then copy the API Key and API Secret into the fields below and then click Test Integration
When your Smile & Pay integration is now live your Payment Provider page should look like this:
Make an Ecocash Payment
Now lets do an Ecocash payment and automatically create a ZIMRA Fiscal Invoice. You need to go to the Create Sale endpoint and use this payload, making sure to replace the customer_id
, product
and phone
with ones from your Panier account:
{
"data": {
"customer_id": "cmaccp0vy0000zmksubook8hd",
"products": [
{
"id": "cma5e7aca0000zm1x9aiabiil",
"selling_price": 0.10,
"quantity": 1
}
]
},
"zimra_fiscalize": true,
"payment_method": {
"type": "SMILE_PAY_ECOCASH",
"phone": "0772000001",
"email": "youremail@gmail.com"
}
}
You should get the following response:
{
"instructions": "Dial *151*2*7# and enter your EcoCash PIN. Once you have authorized the payment via your handset, please click Check For Payment below to conclude this transaction",
"pollurl": "https://panier.app/api/v1/payment-provider/check-payment-status?pollurl=https://zbnet.zb.co.zw/wallet_gateway/payments-gateway/payments/transaction/cmeo4ca3r0000v1f8p5wzc99e/status/check"
}
You need to get your customer to follow the instructions
on how to make the Ecocash payment. Use the pollurl
or Check Payment Status endpoint to check the payment status at regular intervals of about 5 seconds.
When the payment is successful you should get a response like this:
{
"merchantId": "20250711113952",
"reference": "GZSZ1181TOCP",
"orderReference": "cmepw25l9000lv1s07w1gyci9",
"itemName": null,
"amount": 0.10,
"currency": "USD",
"paymentOption": "ECOCASH",
"status": "Completed",
"createdDate": "2025-08-24T18:14:26.416946",
"returnUrl": "https://panier.app?orderReference=cmepw25l9000lv1s07w1gyci9&transactionReference=GZSZ1181TOCP&status=PENDING",
"resultUrl": "https://panier.app/api/v1/payment-provider/smile-pay/webhook",
"clientFee": 0,
"merchantFee": 0,
"pollurl": "https://zbnet.zb.co.zw/wallet_gateway/payments-gateway/payments/transaction/cmeo4ca3r0000v1f8p5wzc99e/status/check",
"sale": {
"id": "cmaxpey550004zm3nthcoocph",
"receipt_number": "IPID5V3JJ87E",
"phone": "0772000001",
"email": "john@cornerbakery.com",
"currency": {
"symbol": "$",
"name": "US Dollar",
"symbol_native": "$",
"decimal_digits": 2,
"rounding": 0,
"code": "USD",
"name_plural": "US dollars",
"exchange_rate": 1
},
"products": [
{
"id": "cma5e7aca0000zm1x9aiabiil",
"name": "Eggs",
"description": "One dozen large eggs",
"buying_price": 2.51,
"sku": "",
"hs_code": "0808.01.01",
"is_inventory_item": true,
"applicable_tax": {
"id": "cmac8znbu0005zm0gdy8xxoi6",
"name": "VAT Exempt",
"percentage": null,
"code": null,
"zimra_tax_id": 1
},
"_selling_price": 0.10,
"_quantity": 1,
"_discount": 0,
"_total_excluding_tax": 0.10,
"_tax": 0,
"_total_including_tax": 0.10
}
],
"total": 0.01,
"discount": 0,
"is_refunded": false,
"refunded_at": null,
"is_voided": false,
"voided_at": null,
"template_preference": {
"template": 1,
"color": "no_color",
"table_layout": "Plain"
},
"updated_at": "2025-05-21T08:51:45.145Z",
"created_at": "2025-05-21T08:51:45.109Z",
"customer": {
"id": "cmaccp0vy0000zmksubook8hd",
"name": "Corner Bakery",
"contact_person": "John Smith",
"phone": "0772000001",
"email": "john@cornerbakery.com",
"address": "123 Road Drive, City, Country",
"fax": "02888881",
"website": "https://example.com",
"tax_reg_number": "",
"company_reg_number": "",
"tin_number": "",
"vat_number": ""
},
"invoice": {
"id": "cmaxpey460002zm3nryg5glz1",
"number": "SSK2BURLOLDA",
"date_format": "dd/mm/yy",
"date_issued": "2025-05-21T08:51:45.073Z",
"recipients": [
"john@cornerbakery.com"
],
"payment_due": "2025-05-21T08:51:45.073Z",
"currency": {
"symbol": "$",
"name": "US Dollar",
"symbol_native": "$",
"decimal_digits": 2,
"rounding": 0,
"code": "USD",
"name_plural": "US dollars",
"exchange_rate": 1
},
"products": [
{
"id": "cma5e7aca0000zm1x9aiabiil",
"name": "Eggs",
"description": "One dozen large eggs",
"buying_price": 2.51,
"sku": "",
"hs_code": "0808.01.01",
"is_inventory_item": true,
"applicable_tax": {
"id": "cmac8znbu0005zm0gdy8xxoi6",
"name": "VAT Exempt",
"percentage": null,
"code": null,
"zimra_tax_id": 1
},
"_selling_price": 0.10,
"_quantity": 1,
"_discount": 0,
"_total_excluding_tax": 0.10,
"_tax": 0,
"_total_including_tax": 0.10
}
],
"total": 0.10,
"discount": 0,
"payment_information": null,
"terms_n_conditions": null,
"sending_status": "Send Email Notification",
"quotation_id": null,
"template_preference": {
"template": 1,
"color": "no_color",
"table_layout": "Plain"
},
"is_paid": true,
"updated_at": "2025-05-21T08:51:45.077Z",
"created_at": "2025-05-21T08:51:45.077Z",
"zimra_receipt": {
"id": "cmaxpey350001zm3n20cv98iv",
"device_id": 24455,
"device_serial_number": "HQAUR8QVG29BBY33",
"receipt_type": "FISCALINVOICE",
"receipt_currency": "USD",
"receipt_counter": 2,
"receipt_global_no": 14,
"receipt_date": "2025-05-21T10:51:44",
"receipt_total": 0.10,
"receipt_taxes": [
{
"taxID": 1,
"taxAmount": 0,
"salesAmountWithTax": 0.10
}
],
"previous_receipt_hash": "RNlOmC9SFzBf1f6teHf1sdRvndEBxRrsLmgTEzs2VEw=",
"result_used_to_hash": "24455FISCALINVOICEUSD142025-05-21T10:51:44101RNlOmC9SFzBf1f6teHf1sdRvndEBxRrsLmgTEzs2VEw=",
"receipt_hash": "O325QgESIiw1oe+91aHtTlHsVrZDYU1QLqcPYTaiGHI=",
"signature": "PZuW4HH4x1fkYwKdMj8YQGVI76IF3eP51cpUHdiq42xnZi1SPEGBN7h5rtECOOLkl6egUhlXWXr35Q+TtBgDHitYuc/2J13iJwhdy3xdZCSlz8NV29d73/lziH80AjBYsOC6fV+vJToSWcYuqdSKeIbgBDcOj6CFvCCQegmU9G0mY/e3uqnmXb29TfhiTUQUNz5Y3X2RRWCCfrpFGEZk/S9PeWnjKY7RxJNrKcl11Yp+9GXYjtpsyrbP42JF6gLcGjPbj436ihUmScDoouNdKLEbWabt5FOjtmdUkJ1Xxv1aEpfjt7Nv03d6zofuQ79otLM41bisn0sFMtIjSLGGow==",
"qr_code_url": "https://fdmstest.zimra.co.zw/0000024455210520250000000014067E79C20E8CEFCE",
"verification_code": "067E-79C2-0E8C-EFCE",
"receipt_data": {
"receipt": {
"receiptType": "FiscalInvoice",
"receiptCurrency": "USD",
"receiptCounter": 2,
"receiptGlobalNo": 14,
"receiptDate": "2025-05-21T10:51:44",
"receiptLinesTaxInclusive": false,
"receiptLines": [
{
"receiptLineType": "Sale",
"receiptLineNo": 1,
"receiptLineHSCode": "08080101",
"receiptLineName": "Eggs",
"receiptLinePrice": 0.10,
"receiptLineQuantity": 1,
"receiptLineTotal": 0.10,
"taxID": 1
}
],
"receiptTaxes": [
{
"taxID": 1,
"taxAmount": 0,
"salesAmountWithTax": 0.10
}
],
"receiptPayments": [
{
"moneyTypeCode": "MobileWallet",
"paymentAmount": 0.10
}
],
"receiptTotal": 0.10,
"receiptPrintForm": "InvoiceA4",
"receiptDeviceSignature": {
"hash": "O325QgESIiw1oe+91aHtTlHsVrZDYU1QLqcPYTaiGHI=",
"signature": "PZuW4HH4x1fkYwKdMj8YQGVI76IF3eP51cpUHdiq42xnZi1SPEGBN7h5rtECOOLkl6egUhlXWXr35Q+TtBgDHitYuc/2J13iJwhdy3xdZCSlz8NV29d73/lziH80AjBYsOC6fV+vJToSWcYuqdSKeIbgBDcOj6CFvCCQegmU9G0mY/e3uqnmXb29TfhiTUQUNz5Y3X2RRWCCfrpFGEZk/S9PeWnjKY7RxJNrKcl11Yp+9GXYjtpsyrbP42JF6gLcGjPbj436ihUmScDoouNdKLEbWabt5FOjtmdUkJ1Xxv1aEpfjt7Nv03d6zofuQ79otLM41bisn0sFMtIjSLGGow=="
},
"invoiceNo": "SSK2BURLOLDA"
}
},
"server_response": {
"receiptID": 5960796,
"serverDate": "2025-05-21T10:51:44",
"receiptServerSignature": {
"certificateThumbprint": "F9B295CA65BA22B94F6D4B27E48D08BF6CD7F7C8",
"hash": "IESbgGq5bHwGtZnm4lzknj785mCkcfTG24hZWP7L65M=",
"signature": "gZC4ZSmOqDiBtXmxaIJF0jTunrFBnRfk9dizbBpGVp62i4+0jopEbkmgjjsShXDGv8NtxNjoeJ6Pi65IdrL7UhQ9dEbeA9x9Lmp8dzko138uMg9Ey9WVYMmHoISSwdHSUuetHUk0x6x2RvyUjaV32RlotHMDoyPhvEjDxkZu/+ar58n+9dCvl5hBP6u2yaFGe5QX6wrr5WxhgPZhkLAqyayPTow2m6LNVVP5GK66VZdC+xRFxealMx2BdbPrxpzHNOb5GmMACfqHz5wvPpMYuZL8LEzSYAJzKzQFbNgRgqNg5YNHKRp2L+vQbEbcy/hszjVn0v3UysFo3xTlYkzXDg=="
},
"validationErrors": [],
"operationID": "0HNCDUV5BOVT4:00000001"
},
"validation_errors": [],
"fiscal_day_no": 4,
"updated_at": "2025-05-21T08:51:45.077Z",
"created_at": "2025-05-21T08:51:45.041Z"
}
}
}
}
Make an Innbucks Payment
Now lets do an Innbucks payment and automatically create a ZIMRA Fiscal Invoice. You need to go to the Create Sale endpoint and use this payload, making sure to replace the customer_id
, product
and phone
with ones from your Panier account:
{
"data": {
"customer_id": "cmaccp0vy0000zmksubook8hd",
"products": [
{
"id": "cma5e7aca0000zm1x9aiabiil",
"selling_price": 0.10,
"quantity": 1
}
]
},
"zimra_fiscalize": true,
"payment_method": {
"type": "SMILE_PAY_INNBUCKS",
"phone": "0772000001",
"email": "youremail@gmail.com"
}
}
You should get the following response:
{
"innbucksPaymentCode": "601822521",
"deep_link_url": "schinn.wbpycode://innbucks.co.zw?pymInnCode=601822521",
"qr_code": "https://chart.googleapis.com/chart?cht=qr&chs=200x200&chl=601822521",
"innbucks_expires_at": "21-May-2025 12:19",
"pollurl": "https://panier.app/api/v1/payment-provider/check-payment-status?pollurl=https://zbnet.zb.co.zw/wallet_gateway/payments-gateway/payments/transaction/cmepw25l9000lv1s07w1gyci9/status/check",
"responseMessage": "success",
"responseCode": "00",
"status": "AWAITING_PAYMENT",
"orderReference": "cmepw25l9000lv1s07w1gyci9",
"transactionReference": "GZSZ1181TOCP"
}
You need to get your customer to follow the instructions
on how to make the Innbucks payment. Use the pollurl
or Check Payment Status endpoint to check the payment status at regular intervals of about 5 seconds.
When the payment is successful you should get a response like this:
{
"merchantId": "20250711113952",
"reference": "GZSZ1181TOCP",
"orderReference": "cmepw25l9000lv1s07w1gyci9",
"itemName": null,
"amount": 0.10,
"currency": "USD",
"paymentOption": "ECOCASH",
"status": "Completed",
"createdDate": "2025-08-24T18:14:26.416946",
"returnUrl": "https://panier.app?orderReference=cmepw25l9000lv1s07w1gyci9&transactionReference=GZSZ1181TOCP&status=PENDING",
"resultUrl": "https://panier.app/api/v1/payment-provider/smile-pay/webhook",
"clientFee": 0,
"merchantFee": 0,
"pollurl": "https://zbnet.zb.co.zw/wallet_gateway/payments-gateway/payments/transaction/cmepw25l9000lv1s07w1gyci9/status/check",
"sale": {
"id": "cmaxsdzpl000rzm0dqilmlkh0",
"receipt_number": "KMY7WYXEMOM9",
"phone": "0772000001",
"email": "john@cornerbakery.com",
"currency": {
"symbol": "$",
"name": "US Dollar",
"symbol_native": "$",
"decimal_digits": 2,
"rounding": 0,
"code": "USD",
"name_plural": "US dollars",
"exchange_rate": 1
},
"products": [
{
"id": "cma5e7aca0000zm1x9aiabiil",
"name": "Eggs",
"description": "One dozen large eggs",
"buying_price": 2.51,
"sku": "",
"hs_code": "0808.01.01",
"is_inventory_item": true,
"applicable_tax": {
"id": "cmac8znbu0005zm0gdy8xxoi6",
"name": "VAT Exempt",
"percentage": null,
"code": null,
"zimra_tax_id": 1
},
"_selling_price": 0.01,
"_quantity": 1,
"_discount": 0,
"_total_excluding_tax": 0.01,
"_tax": 0,
"_total_including_tax": 0.01
}
],
"total": 0.01,
"discount": 0,
"is_refunded": false,
"refunded_at": null,
"is_voided": false,
"voided_at": null,
"template_preference": {
"template": 1,
"color": "no_color",
"table_layout": "Plain"
},
"updated_at": "2025-05-21T10:14:59.357Z",
"created_at": "2025-05-21T10:14:59.338Z",
"customer": {
"id": "cmaccp0vy0000zmksubook8hd",
"name": "Corner Bakery",
"contact_person": "John Smith",
"phone": "0772000001",
"email": "john@cornerbakery.com",
"address": "123 Road Drive, City, Country",
"fax": "02888881",
"website": "https://example.com",
"tax_reg_number": "",
"company_reg_number": "",
"tin_number": "",
"vat_number": ""
},
"invoice": {
"id": "cmaxsdzor000pzm0dnh8cfbtl",
"number": "39DC6U5EM65J",
"date_format": "dd/mm/yy",
"date_issued": "2025-05-21T10:14:59.305Z",
"recipients": [
"john@cornerbakery.com"
],
"payment_due": "2025-05-21T10:14:59.305Z",
"currency": {
"symbol": "$",
"name": "US Dollar",
"symbol_native": "$",
"decimal_digits": 2,
"rounding": 0,
"code": "USD",
"name_plural": "US dollars",
"exchange_rate": 1
},
"products": [
{
"id": "cma5e7aca0000zm1x9aiabiil",
"name": "Eggs",
"description": "One dozen large eggs",
"buying_price": 2.51,
"sku": "",
"hs_code": "0808.01.01",
"is_inventory_item": true,
"applicable_tax": {
"id": "cmac8znbu0005zm0gdy8xxoi6",
"name": "VAT Exempt",
"percentage": null,
"code": null,
"zimra_tax_id": 1
},
"_selling_price": 0.01,
"_quantity": 1,
"_discount": 0,
"_total_excluding_tax": 0.01,
"_tax": 0,
"_total_including_tax": 0.01
}
],
"total": 0.01,
"discount": 0,
"payment_information": null,
"terms_n_conditions": null,
"sending_status": "Send Email Notification",
"quotation_id": null,
"template_preference": {
"template": 1,
"color": "no_color",
"table_layout": "Plain"
},
"is_paid": true,
"updated_at": "2025-05-21T10:14:59.307Z",
"created_at": "2025-05-21T10:14:59.307Z",
"zimra_receipt": {
"id": "cmaxsdzoc000ozm0dee2jtytg",
"device_id": 24455,
"device_serial_number": "HQAUR8QVG29BBY33",
"receipt_type": "FISCALINVOICE",
"receipt_currency": "USD",
"receipt_counter": 4,
"receipt_global_no": 16,
"receipt_date": "2025-05-21T12:14:58",
"receipt_total": 0.01,
"receipt_taxes": [
{
"taxID": 1,
"taxAmount": 0,
"salesAmountWithTax": 0.01
}
],
"previous_receipt_hash": "fNFmaw6tK30NEVJP/bF0wIp5S0xWMrRu6EG8EFOJ/ss=",
"result_used_to_hash": "24455FISCALINVOICEUSD162025-05-21T12:14:58101fNFmaw6tK30NEVJP/bF0wIp5S0xWMrRu6EG8EFOJ/ss=",
"receipt_hash": "qUk5/6/cdCyoo/T2FTk9mq2tPHDDp1tNgo/pG11fwoU=",
"signature": "AfuRWXk1X2Hw5wjjiPizGQAdug6M+e5+jQ7iSFXabPgmXTGRzhcw3EH6LEiAX6B/MN+c2l15x0DTBqN51C0Z97MvL+DPhq0+skb0CJoFydLJBAzYhR/nf6tZvIIcokYWHl6rtSVr3bgF8XNpEB8Q6foN+dn2CpLlvZdwB4eqRu5o8oxjoTH/VKbChDdGeWYwjuwYiMPGPdB2Ov1sFSIcNNHL2qkmhoE4balSugYvjhagNLDca27r2S2uXJSHZh+70BregHuxYr5xuWUNbiP6NmeZl8T8VB8lm8i/oDl7WC22sTePYObggygOkbjvguk0kp2mktwahDlY3tqELnk9fg==",
"qr_code_url": "https://fdmstest.zimra.co.zw/0000024455210520250000000016737506EB7E49AE71",
"verification_code": "7375-06EB-7E49-AE71",
"receipt_data": {
"receipt": {
"receiptType": "FiscalInvoice",
"receiptCurrency": "USD",
"receiptCounter": 4,
"receiptGlobalNo": 16,
"receiptDate": "2025-05-21T12:14:58",
"receiptLinesTaxInclusive": false,
"receiptLines": [
{
"receiptLineType": "Sale",
"receiptLineNo": 1,
"receiptLineHSCode": "08080101",
"receiptLineName": "Eggs",
"receiptLinePrice": 0.01,
"receiptLineQuantity": 1,
"receiptLineTotal": 0.01,
"taxID": 1
}
],
"receiptTaxes": [
{
"taxID": 1,
"taxAmount": 0,
"salesAmountWithTax": 0.01
}
],
"receiptPayments": [
{
"moneyTypeCode": "MobileWallet",
"paymentAmount": 0.01
}
],
"receiptTotal": 0.01,
"receiptPrintForm": "InvoiceA4",
"receiptDeviceSignature": {
"hash": "qUk5/6/cdCyoo/T2FTk9mq2tPHDDp1tNgo/pG11fwoU=",
"signature": "AfuRWXk1X2Hw5wjjiPizGQAdug6M+e5+jQ7iSFXabPgmXTGRzhcw3EH6LEiAX6B/MN+c2l15x0DTBqN51C0Z97MvL+DPhq0+skb0CJoFydLJBAzYhR/nf6tZvIIcokYWHl6rtSVr3bgF8XNpEB8Q6foN+dn2CpLlvZdwB4eqRu5o8oxjoTH/VKbChDdGeWYwjuwYiMPGPdB2Ov1sFSIcNNHL2qkmhoE4balSugYvjhagNLDca27r2S2uXJSHZh+70BregHuxYr5xuWUNbiP6NmeZl8T8VB8lm8i/oDl7WC22sTePYObggygOkbjvguk0kp2mktwahDlY3tqELnk9fg=="
},
"invoiceNo": "39DC6U5EM65J"
}
},
"server_response": {
"receiptID": 5961141,
"serverDate": "2025-05-21T12:14:59",
"receiptServerSignature": {
"certificateThumbprint": "F9B295CA65BA22B94F6D4B27E48D08BF6CD7F7C8",
"hash": "aWJBHwqQR2M40iWgiVEAqtc8UtrFBKkz0eRoBkGPXdc=",
"signature": "F35BHzB5BHurc3jEBsVeexZNkl8kwpQn4Sp8K1xGr13SjEqKdF6WkkPo9xqBBAJ8jQHZunnINrX0nluPbMUmJIte5Cea9esth95nH68fiMWhSdtWR3ikmrQ61+KxJKSCGX9rLzVcQzvYDX7jjVO8WEU5tLymrM0uCMZWMQ4npDsNK9aLRekcbf9L+2kFJLnMqs4qf2/PMvFsvIRCFdrQXOYYFzPDm8LuKpCx3yybS9RIG/7b4JmQ4auOmrEQxaGH+TWUPlxtjeJTFM8nUY7G/Afhpe7txJGs/X3ksHgw0CzdCgz5eEZC23tjfAs1UBKtyWowP7LTuL6CxkbhFYfnVg=="
},
"validationErrors": [],
"operationID": "0HNCDUV5BQ539:00000001"
},
"validation_errors": [],
"fiscal_day_no": 4,
"updated_at": "2025-05-21T10:14:59.307Z",
"created_at": "2025-05-21T10:14:59.292Z"
}
}
}
}
If your customer was created with an email address in your Panier account, they will receive a PDF attached email like this:
Closing Statement
We also recommend that you go over our article on ZIMRA Fiscalisation with the Panier API: A Step-by-Step Guide so that you can also learn how to Create Credit Notes and Create Debit Notes. If you have any questions feel free to ask in the comments section or contact me directly on support@panier.app and I will get back to you has quickly as I can.
Top comments (0)