Implementation Guide

At the core, we want to ensure data is in sync between your system and marketpe. In your system, a payment is identified by a unique clientPaymentId.

There are only few cases for clientPaymentId in marketpe:

does not exist in marketpe
exists in marketpe
- status = NEW
- status = CANCELLED (terminal state)
- status = COMPLETED (terminal state)
- status = PROCESSING
- status = FAILED

Your system calls payment/create api

This pseudo code explains what all cases you may encounter while calling payment/create api.

// PSEUDO CODE, NOT ACTUAL LOGIC

function initiatePRinMarketpe() {
    // we do not know if marketpe api will pass, fail or timeout
    // let's lock payment before even calling the api
    freeze(your_system.payment)

    response = await marketpe.paymentApi.create()

    if (response.status === 'success') {
        // ✅ PR was created in marketpe successfully 
        save(response.data.id) // save marketpe generated id
        return;
    }

    if (response.status === 'error' && response.message === 'clientPaymentId already exists') {
        // same clientPaymentId was already used
        // did we already create same already in marketpe?
        return;
    }
    
    if (response.status === 'error' && response.errorCode === 'schema_validation_failed') {
        // ❌ PR was NOT created in marketpe because of validation errors
        // we can fix and retry `payment/create` api with same clientPaymentId
        // or show error to user
        return;
    }

    if (response.status === 'error' && response.errorCode === 'failed') {
      // ❌ expected error, PR was not created in marketpe
      // error description is in response.message
      return;
    }

    // 🤷🏻‍♂️ for any other error, we are unsure what happened.
    // clientPaymentId may or may not have been created in marketpe.
    // best to use `payment/get` api to check if `clientPaymentId` was created or not.
    return;
}

Sync status in your system

Based on the Payment object data, you may do various updates to your system's data.

For example:

when status is COMPLETED, you update utr in your system.
when status is CANCELLED, you mark the same in your system.

// PSEUDO CODE, NOT ACTUAL LOGIC

function checkPRinMarketpe(clientPaymentId: string) {
  response = await paymentApi.get(clientPaymentId);

  if (response.message === "PR not found") {
    // PR is not found in marketpe
    // maybe call payment/create again?
    // or mark as not created in your system
    return;
  }

  const paymentObject = response.data;

 if (paymentObject.status === "COMPLETED") {
    // PR is completed and in terminal state
    // update utr in your system
    return;
  }

  if (paymentObject.status === "CANCELLED") {
    // PR is cancelled and in terminal state
    // mark the same in your system
    return;
  }

  // PR exists in marketpe but not in terminal state
  // maybe do nothing till it reaches terminal state
  return;
}

Business logic to cancel a PR

Suppose you created a PR via payment/create. For some reason, you decide that you want to cancel the PR.

Possible reasons:

Amount is wrong.
That bank account is down and PR is failing.
vpa has reached daily limit and PR is failing.

Before allowing to raise a new request in your system, you want to cancel the existing PR to avoid this payment from being executed later.

How you handle your system's flow is your choice, whether you show an edit button or user needs to raise a new request. Just ensure, you first cancel the PR in marketpe before allowing and approving a new payment for the same. You will still need to generate a new clientPaymentId as this is a new PR for marketpe.

Implementation Guide

Your system calls payment/create api

Sync status in your system

Business logic to cancel a PR

On this page