Usage#

Common terms#

Understanding the workflow and integration process will be easier if you are familiar with these common terminologies and concepts that are used throughout this document.

  • Merchant/Seller/Receiver Any user who wants to collect payments or receive money through YenePay

  • Buyer/Sender An end user or a customer that is making a payment for purchasing a product or service

  • Checkout Checkout is the process of selecting a payment method and completing a payment.

  • Merchant ID/Seller Code/User Code This is an ID that is used to uniquely identify a YenePay customer. This is required to successfully integrate with YenePay and track transactions made. A seller code is an all-digit code with a minimum length of 4 digits.

  • Order Code An Order Code is an ID that is used to uniquely identify a transaction made through YenePay and ties information about the buyer, the merchant, the purchased items and the amount paid. This order code can also be used to get details of the payment made after the payment has been completed.

  • Instant Payment Notification (IPN) After YenePay processes the payment order initiated from your website or app by your customers, YenePay system sends a notification called Instant Payment Notification (IPN) to your website or app to the IPNUrl you have configured on your YenePay account settings OR the IPNUrl that is sent with the payment request body. It is strongly recommend you have an IPN URL on your website or app ready to accept notifications.

  • Payment Data Transfer (PDT) Payment Data Transfer is used by merchants to check the current status of an initiated payment order from their sites. This provides an alternative method to check a payment’s current state at any time.

  • Cancel URL The absolute URL on your site the buyer will be redirected to when a payment process is cancelled.

  • Failure URL The absolute URL on your site the buyer will be redirected to when an error happens during the payment process.

  • IPN URL The absolute URL on your site that will be used to send you IPNs. If this field is left empty when making a request, the default IPN URL you provided on your account’s settings page will be used instead.

  • Success URL The absolute URL on your site the buyer will be redirected to when the payment process has successfully been completed.

Read from https://community.yenepay.com/docs/getting-started/common-terms/

Client#

yenepay.models.client.Client instance represents a single merchant account in YenePay platform.

Creating client#

Inorder to create a client instance it is required to have a merchant/seller code. If you don’t have one, first need to register on YenePay as a merchant and get your seller code. Read how you would get one from https://community.yenepay.com/docs/getting-started/get-your-seller-merchant-code/

from yenepay import Client

client = Client(merchant_id="0000")

If you are going to check PDT status of you payment order, you must provide PDT token for your client instance. You can find your pdt token from your YenePay profile section.

from yenepay import Client

client = Client(merchant_id="0000", token="abcd")

When ever you have a sandbox merchant ID and PDT token you must set use_sanbox=True while you create instance. Default is set to False

from yenepay import Client

client = Client("0000", "abcd", use_sandbox=True)

# You can check whether client is using sanbox or not use `is_sandbox` attribute
client.is_sandbox # True

Warning

If you use sandbox account details (merchant id and/or PDT token) without using use_sanbox=True will raise yenepay.exceptions.CheckoutError

Generating checkout url#

If you have a client instance you can create checkout url directly using yenepay.models.client.Client.get_express_checkout or yenepay.models.client.Client.get_cart_checkout. You can check function parameters from yenepay.models.checkout.Checkout

Creating express checkout#

Using a function yenepay.models.client.Client.get_express_checkout can generate checkout link.

from yenepay import Client, Item

client = Client("0000") # send your merchant id as first parameter

# Create item
item = Item("PC-1", 34_000.99, 1)

express_checkout = client.get_express_checkout(item)

checkout_url = express_checkout.get_url() # returns checkout url

Creating cart checkout#

Using a function yenepay.models.client.Client.get_cart_checkout can generate checkout link.

from yenepay import Cart, Client, Item

client = Client("0000") # send your merchant id as first parameter

# Create item
cart = Cart(
    Item("PC-1", 39_999.99, 1),
    Item("PC-2", 40_000.00, 1),
    Item("PC-3", 55_000.99, 1),
)

cart_checkout = client.get_express_checkout(cart)

checkout_url = cart_checkout.get_url() # returns checkout url

Checking PDT status#

If you want to check whether your payment order is paid or not, you can send pdt request to YenePay server using yenepay.models.pdt.PDT class. Before checking you payment order status you need to have merchant_order_id and transaction_id. You can create merchant_order_id when you are creating checkout (express or cart). You can get your transaction id from success_url when a payment is completed.

from yenepay import Client, Item

client = Client("0000", "abcd")

mo_id = "m01x"

# Prepare checkout process
express_checkout = client.get_express_checkout(
    Item("TV", 13_000.00, 1),
    merchant_order_id=mo_id,
    success_url="localhost:8000",
    # User will redirected to this url after transaction is completed.
    # Required for checking pdt status
)

checkout_url = express_checkout.get_url()

"""
Send `checkout_url` to you customers, and check payment status
when your `success_url` endpoint is called.
"""

# return yenepay.PDTResponse instance on success
pdt_status = client.check_pdt_status(
            mo_id, # merchant order id
            "01cd13eae42", # transaction id
        )

pdt_status.result # Success

pdt_status.status # Paid

pdt_status.buyer_id # 1103cdca12


# Or you ca checkfrom checkout instance

pdt_status = express_checkout.check_pdt_status("01cd13eae42") # transaction id