API documentation

# 4.1 Introduction to Wallet V3

# 4.1.1 Glossary

Token (Refresh) - This token is obtained by a “Server to Server” API call prior to initializing the wallet. Documentation can be found in the link

Token (Access) - This token is obtained by a “Server to Server” API call prior to initializing the wallet. Documentation can be found in the link

Checkout View - refers to one of the two optional modes of the wallet. This view is typically being used on the checkout page.

Manage View - refers to one of the two optional modes of the wallet. This view is typically being used on a profile section and allows the users to manage their payment methods for future usage. In this view, "Checkout Ready" event will always be false and checking out via 3rd party provider (such as Apple Pay) will not be possible.

Manage Screen - Refers to a page within Checkout View. This page will appear when the user clicks on "Manage Payment Info". The page is designed to allow the user to select a different payment method for the checkout. In this page, " Checkout Ready" event will always be false and checking out via 3rd party provider (such as Apple Pay) will not be possible.

Merchant ID - Configured on the Shiji side to indicate the processor/gateway you are using for payments and credit card verifications. This parameter should be provided to you during the onboarding process.

Instant payments - refers to a payment flow within the wallet. In this flow, the user is being redirected to a 3rd party provider to complete the transaction (for example: Apple Pay, iDeal etc)

Alternative Payments - Refers to a flow where the card is being added using a 3rd party such as Gpay/ PayPal

"return_url" parameter - the return URL to be redirected to in case of an instant payment

"callback_url" parameter - the callback URL to be notified about an instant payment’s result

# 4.1.2 Best practices

Below are best practices that should ease up the integration and prevent incorrect usage.

  1. Always load your checkout page with the “checkout” button disabled
  2. Load the wallet only when you know the payment price and the currency (supply it to the init() method)
  3. Wallet initialization sequence should be:
    • Start listening to the “checkoutReady” event
    • Invoke mycheck.auth.connect
    • Invoke mycheck.wallet.init
  4. Note that the wallet payment details amount should always be the total amount. (Tip included). If at any point the total amount (tip included) or currency are changed after the call to mycheck.wallet.init has been made, please make sure to call mycheck.wallet.setPaymentDetails with the relevant updated information
  5. Start listening to the “checkoutReady” event (for the whole duration of activity)
  6. When the “checkoutReady” event returns the “status” as false – it means that no payment can be made currently. You should disable your “checkout” button on these cases.
  7. When the “checkoutReady” event returns the “status” as true – that means that a payment can be made as far as the sdk is concerned and you should enable your “checkout button”. (Though this decision can be dependent on your own flow and constraints to proceed with checkout, beside our indication.)
  8. If you decide to not rely on our indication to enable or disable your button, it is advised that if the end user presses your button and the “checkoutReady” is false, please highlight the wallet SDK frame in red and direct the user view to the frame. The actions required will be presented to the user in the wallet SDK. In addition, you can place a generic message requesting the user to add/select a payment method.
  9. When “checkoutReady” event “status” is true, if “paymentDetails.type” is “instant” (instant payment is a 3rd party's alternative payment such as Alipay, WechatPay, iDeal, Payconiq etc...), you should trigger the payment by calling mycheck.wallet.makeInstantPayment()
    • A QR code or a deeplink will be triggered according to the payment type.
  10. When “checkoutReady” event “status” is true, if “paymentDetails.type” is “traditional” or “alternative” you should use your own logic in order to contact your server and from there, make a server to server call for billing
  11. In case you are using MyCheck’s APIs, make sure to never manipulate the objects obtained by wallet SDK (for example: CC token, fingerprint structure etc)
  12. Listen to “paymentCompleted” event to know when to redirect the user to your order confirmation page. (This is optional in case of a simple traditional payment(auth\sale\charge), where you can use your own server to notify you as the server already receives the final response)
  13. On any case in which you are not sure what has happened with a transaction (mostly applicable to 3DS transactions as they are Async), for example following a page refresh for guest users, or any other case, please invoke the api of get transaction details, in order to get the real status of the transaction and continue your flow accordingly.

# 4.1.3 Important notes

  1. Wallet V3 can be used for 3DS2 calls. In this case, you will need to modify your billing calls according to the details in this section
  2. Once the user has entered their CVV, it will expire in 10 minutes.
    • If the user stays on the checkout page for more than 10 minutes, they will need to re-enter the CVV. (Applicable to 3ds2 transactions only)
    • In the case of 3DS transactions, the CVV will expire once the challenge frame opens. The wallet will simultaneously fire the checkoutReady event as false
  3. Please note if the user closed the challenge window, the 3DS transaction will change status to "failed". In this case the user can attempt to reenter a CVV and try a new transaction.

← 4.2 Adding the wallet client →