Digital wallets

Index

Explanation Document for Integration with Bit

(Including API requests, iFrame, and local interface)

Pelecard offers an advanced payment interface that also supports payments via the Bit digital wallet.
The merchant must register with Gama and get ClientId (username) and ClientSecret (password) from them.

Important Notes:

  • The merchant must have a terminal with Pelecard that supports IFrame 2.0 / Plugin / LinkBeClick.
  • It is possible to use ServicesAPI in manual mode only – (further explanation is provided later in this document).
  • A merchant using a payment page with fund authorization (pre-authorization) must integrate Bit by embedding code – a developer should be involved.
    The transaction completion can be done using the ServicesAPI call (explained later).
    Alternatively, go to לדוחות > איתור אישורים > Select relevant authorization fund> ‘בחר סכום וחייב אישור.’.
  • A Bit transaction will appear in the Pelecard Reports system under “איתור עסקאות אחרי שידור” tab.
  • Every Bit transaction is a real transaction. If you need to cancel it, you must do so through the Pelecard Reports system:
    https://reports.pelecard.biz > איתור עסקאות אחרי שידור > Click the row > Click “Cancel”.

Example of a Transaction via Bit

  1. The transaction will immediately appear under “איתור עסקאות אחרי שידור”
  2. The last 4 digits of the card appear only in the charge stage (J4). In pre-authorization (איתור אישורים), no card info is shown.
  3. On the customer’s Bit app, the charge will appear under “Gama”.

Explanation and Demonstration - Bit

Introduction:
At this stage, we will present how to operate a transaction using the Bit interface via the payment page, API, or Belclient/Madaf interface.
An explanation regarding the API request and/or the required fields to create the payment page appears at the end of this document.

Charging via Payment Page:

  • Open the payment page.

 

  • Select the Bit screen (except for merchants who have set Bit as the default option when generating the payment page), and fill in the required details including the phone number.
    Click ‘בצע תשלום’ at the end.

 

  • A pop-up window will appear on the payment page. At this stage, an SMS message will be sent to the phone number entered in the payment page.

 

  • Receiving the message: When opening the SMS message, the customer’s name (as entered in the payment page) will appear, along with a link to click and open the application.

 

  • By clicking the link, the user will be redirected to the application, to the payment approval screen. Upon clicking “אישור התשלום” (if the payment is successful), an approval will be shown in the application, and the payment page will redirect to the landing page

Bit with Belclient/Madaf Interface:

  • A request is made from the management software to the “Belclient/Madaf” interface. A Pelecard window will pop up, where it’s possible to select payment via “bit”.

 

  • Enter the required details and click on “בצע עסקה”

  • Immediately after that, a Pelecard helper window will display the “התקדמות” of the transaction. At the same time, an SMS message will already be sent to the customer


  • Receiving the message: When opening the SMS message, the customer’s name (as entered in the “Belclient/Madaf”) will appear, along with a link to click and open the application.

  • By clicking the link, the user will be redirected to the application, to the payment approval screen. Upon clicking “אישור התשלום” (if the payment is successful), a transaction approval will be received, the “Belclient” window will close, and the management software will receive the transaction details.

The transaction process is complete.

Bit With AΡΙ

It is possible to initiate a Bit charge request via RestAPI. There are two methods: actual charge (J4) or fund authorization (J5).

To control which method is used, the appropriate ActionType (J4/J5) must be passed in the method. https://gateway21.pelecard.biz/services/DebitGamaTransaction

Request:

				
					{
  "User": "",
  "Password": "",
  "TerminalNumber": "",
  "Total": "100",
  "Description": "",
  "CardHolderName": "test",
  "Phone": "",
  "ActionType": "j5",
  "Currency": 376
}

Response:

				
					{
  "StatusCode": "000",
  "ErrorMessage": "Operation successful",
  "ResultData": {
    "DebitTrxId": 0,
    "GamaRecordid": 69333
  }
}

The “GamaRecordId” identifier must be saved – it will be used in the following method.

At this stage, the customer receives an SMS as shown in the example. The customer opens the message, clicks the link, and is redirected to the application to continue the process.

Checking the status of an in-progress transaction:

Make a request to the method:
https://gateway21.pelecard.biz/services/DebitGamaStatus

Request:

				
					{
  "terminalNumber": "",
  "user": "",
  "password": "",
  "GamaRecordId": 69333
}

Response for a transaction still in progress (the customer has not yet completed the action in the application):

				
					{
  "StatusCode": "553",
  "ErrorMessage": "Transaction in process"
}

Response for a transaction canceled by the user (if the user clicked "X" in the application):

				
					{
  "StatusCode": "000",
  "ErrorMessage": "Operation successful",
  "ResultData": {
    "EmvInOut": {},
    "ashStatus": "705",
    "ashStatusDes": "Transaction canceled by user",
    "DebitTrxId": 0,
    "TerminalNumber": "",
    "Token": "0123456789",
    "GamaRecordId": 69333,
    "GamaResult": {
      "GamaTransactionId": "F211048D-5407-4196-9F7F-D4CC4F89CCC0",
      "GamaTransactionProcessingId": "",
      "GamaWalletProviderPaymentInitiationId": "",
      "GamaWalletProviderTransactionSerialId": "",
      "GamaPaymentNetwork": "",
      "GamaLastStatus": ""
    }
  }
}

Response for a transaction that was successfully completed:

				
					{
  "StatusCode": "000",
  "ErrorMessage": "Operation successful",
  "ResultData": {
    "EmvInOut": {
      "amount": "100",
      "ashStatus": "000",
      "ashStatusDes": "operation success",
      "authCodeManpik": "1",
      "authManpikNo": "2485538",
      "brand": "104",
      "currency": "376",
      "manpik": "104",
      "panEntryMode": "69",
      "parameter": "5",
      "solek": "104",
      "tranType": "1"
    },
    "DebitTrxId": 1111111111,
    "TerminalNumber": "",
    "Token": "0123456789",
    "GamaRecordId": 69331,
    "GamaResult": {
      "GamaTransactionId": "48029573-8A1F-4E4F-A616-501762485538",
      "GamaTransactionProcessingId": "",
      "GamaWalletProviderPaymentInitiationId": "",
      "GamaWalletProviderTransactionSerialid": "",
      "GamaPaymentNetwork": "",
      "GamaLastStatus": ""
    }
  }
}

The “GamaTransactionld” identifier must be saved – it will be used for refunds or transaction completion.

If the “ActionType” is “J4” – the process ends at this stage. If it is “J5” – an explanation follows on the next page.

If the ActionType is J5 – the transaction must be completed by making a request to the following method using the “GamaTransactionld” from the J5 action. https://gateway21.pelecard.biz/services/GamaCaptureTransaction

				
					{
  "terminalNumber": "",
  "user": "",
  "password": "",
  "GamaTransactionId": "48029573-8A1F-4E4F-A616-501762485538",
  "ClientId": "",
  "ClientSecret": ""
}

Success Response:

				
					{
  "StatusCode": "000",
  "ErrorMessage": "Operation successful",
  "ResultData": {
    "EmvInOut": {
      "amount": "100",
      "ashStatus": "000",
      "ashStatusDes": "operation success",
      "authCodeManpik": "1",
      "authManpikNo": "2485538",
      "brand": "104",
      "currency": "376",
      "manpik": "104",
      "panEntryMode": "69",
      "parameter": "4",
      "solek": "104",
      "tranType": "1"
    },
    "DebitTrxId": 1111111111,
    "TerminalNumber": "",
    "Token": "0123456789",
    "GamaRecordId": 69331,
    "GamaResult": {
      "GamaTransactionId": "48029573-8A1F-4E4F-A616-501762485538",
      "GamaTransactionProcessingId": "",
      "GamaWalletProviderPaymentInitiationId": "",
      "GamaWalletProviderTransactionSerialId": "",
      "GamaPaymentNetwork": "",
      "GamaLastStatus": ""
    }
  }
}

Issuing a refund:

Make a request to the method:
https://gateway21.pelecard.biz/services/RefundGamaTransaction

				
					{
  "User": "",
  "Password": "",
  "TerminalNumber": "",
  "GamaTransactionId": "D83B260D-BE75-445B-A5D7-F7F79487F97A",
  "Amount": "100",
  "Description": "טסט",
  "clientid": "",
  "ClientSecret": ""
}

Success Response:

				
					{
  "StatusCode": "000",
  "ErrorMessage": "operation success",
  "ResultData": {
    "OperationResultCode": "Successfull",
    "RefundresponseCode": "True"
  }
}

Error Response:

				
					{
  "StatusCode": "200",
  "ErrorMessage": "bit - General error",
  "ResultData": {
    "OperationResultCode": "Successfull",
    "RefundresponseCode": "False"
  }
}

Bit – Iframe/Redirect

When creating a payment page, the merchant has three options:

  • Configuration on Pelecard’s side – the merchant does not modify the sent “Request”, and the relevant data to activate “Bit” will be added by the system automatically.
  • Full configuration by the merchant, including all parameters sent – explanation below.
  • If generating an IFRAME request with ActionType = J5, you must call the GamaCaptureTransaction method to complete the transaction.

The transaction can also be completed through the Pelecard Reports system:
https://reports.pelecard.biz < “איתור אישורים” screen.

To initiate the page, a request should be sent to the method:
https://gateway21.pelecard.biz/PaymentGW/init

The following parameters must be included in addition to the full Request JSON:

				
					{
  "Gamapay": {
    "ClientId": "",
    "ClientSecret": "",
    "Bit": {
      "Enable": "True",
      "WalletText": "",
      "bit_btn_text": "",
      "bit_btn_alt_text": "",
      "bit_pop_up_confirmation_text": "",
      "bit_confirmation_message_text": "",
      "bit_sms_only_link": "False"
    }
  }
}

Parameter Table:

 

שם השדה הסבר ערך לדוגמה הערות
GamaPay
ClientId מספר לקוח בגמא XXXXXXX מסופק ע”י צוות השיווק
ClientSecret סיסמה בגמא XXXXXX מסופק ע”י צוות השיווק
BIT
Enable כפתור מאופשר / לא מאופשר True/False
WalletText שם בית העסק שיופיע באפליקציית Bit כחלק מבקשת התשלום פלאקארד בע”מ
bit_btn_text הטקסט שיופיע מתחת לכפתור ב-IFRAME תשלום ב-bit מומלץ כברירת מחדל
bit_btn_alt_text טקסט לקורא מסך (נגישות) לחץ לתשלום ב-bit מומלץ כברירת מחדל
bit_pop_up_confirmation_text טקסט כפתור השליחה בטופס התשלום של Bit בתוך ה-IFRAME, השולח את העסקה לתשלום שלח אליי SMS לאישור תשלום מומלץ כברירת מחדל
bit_confirmation_message_text כותרת טופס התשלום במסך הבא לתשלום Bit ב-IFRAME מלאו את הפרטים הבאים כדי להמשיך בתשלום מאובטח באפליקציית bit: מומלץ כברירת מחדל
bit_sms_only_link האם לשלוח SMS ללקוח עם קישור להשלמת התשלום באפליקציה
*נכון לעכשיו, לא קיימת אופציה אחרת		 True חובה.
*נכון לעכשיו, נתמך רק ערך True לשדה זה. False ייתמך מסוף מרץ 2024.

After the customer completes all the required actions both on the payment page and in the application, a request can be made to the method:
https://gateway21.pelecard.biz/PaymentGW/GetTransaction

This method retrieves the transaction data using the Transactionld identifier from Pelecard.

Request:

				
					{
  "terminal": "",
  "user": "",
  "password": "",
  "TransactionId": ""
}

Response:
 Additional fields related to “Bit” will be returned. This way, the GamaTransactionld can be retrieved.

				
					{
  "GamaData": {
    "GamaTransactionId": "21372797-F01F-407A-93C3-EE4281499738",
    "GamaTransactionProcessingId": "129268",
    "GamaWalletProviderPaymentInitiationId": "",
    "GamaWalletProviderTransactionSerialId": "",
    "GamaPaymentNetwork": "bit",
    "GamaLastStatus": "approved"
  }
}

A few important notes:

  • The Issuer/Acquirer/Brand will always appear as 104 in the response (104 = “עסקת ביט”).
  • The Transaction source (how the transaction was performed) will always be 69 (DebitCode / PanEntryMode).
  • The returned Token ID will always be “0123456789”.

Apple Pay

הפעלת כפתור לארנק דיגיטלי apple pay מתוך האייפריים

				
					  "ApplePay": {
    "Enabled": true,
    "Label": "test transaction"
  }
}

General Notes

  1. The parameters must be sent with the request to https://gateway21.pelecard.biz/PaymentGW/init
    as part of the code initiating the transaction.    Example of an INIT request:
    https://gateway21.pelecard.biz/PaymentGW/init
				
					{
  "terminal": "xxxxxx",
  "user": "xxxxx",
  "password": "xxxxxxx",
  "ActionType": "J4",
  "Currency": "1",
  "Total": "100",
  "GoodURL": "https://gateway21.pelecard.biz/sandbox/landingpage",
  "ApplePay": {
    "Enabled": "true",
    "Label": "test"
  }
}
  • The Apple Pay “pay” button will be displayed in the following cases:
    • a. iPhone device
    • b. Mac computer with fingerprint authentication
    • c. Safari browser
  • To embed the button in an IFRAME flow, follow these steps: (For merchants working with Redirect – this is not required)
    • Pelecard will receive the merchant’s website domain and issue a validation file from ApplePay.
    • This text file, received from Pelecard, must be placed at: https://[Domain]/.well-known
    • After embedding the file, the merchant must notify Pelecard so that Pelecard can run a validation process with Apple.
    • If the SSL certificate is not updated at least one week before expiration, Pelecard will need to issue a new validation file and resend it to the merchant.
    • It is recommended to update the SSL certificate early to avoid service interruption.
    • The following JS script must be embedded inside the HTML code under the <body> tag:
      <script src=”https://gateway21.pelecard.biz/Scripts/Payment/ClientSecure.js” type=”text/javascript”></script>
  • It is not possible to generate a token only using J5 or J2 with Apple Pay and later perform a recurring charge using the token. The supported options are:
    • ActionType = J4 → Perform a charge using the card number
    • ActionType = J5 → Perform a pre-authorization with the transaction amount and then capture it later → Use: CreateToken = True The approval number and token generated by the Pelecard IFRAME will be: Approval No / DebitApproveNumber. Supported capture methods:
    • a. Pelecard Reports system – https://reports.pelecard.biz,
      under the tab “איתור אישורים “
    • b. Using one of the REST API methods: CompleteDebitByUid / DebitRegularType / DebitPaymentsType Note about ActionType = J5: Merchants who already have a process for capturing pre-authorizations can use the same process without changes. As with non-wallet transactions, the merchant must use the Approval Number + Token from Pelecard to finalize the charge – the same applies to wallet-based transactions.
  • Wallet transactions are 3D Secure transactions.
  • Refunds can be made using the Pelecard token received during the charge.
  • Pelecard can enable Apple Pay internally, removing the need for the merchant to implement the code manually in the IFRAME INIT request:
				
					{
  "ApplePay": {
    "Enabled": "true",
    "Label": "test transaction"
  }
}
  • To locate a transaction in the Pelecard Reports system (https://reports.pelecard.biz),
    search by:

    • The last 4 digits of the virtual card (returned in the response)
    • Transaction amount
    • Date The customer can find their virtual card number in their wallet app.
  • Merchants who want to display a separate IFRAME with Apple Pay only must include the following parameter in the INIT request:
				
					{
  "CreditCard": {
    "Enable": "false"
  }
}

Important to Know!

  • The card number returned from the transaction is a virtual card number – not the real customer card.
  • If you need to investigate a transaction with the customer, ask them to check the last 4 digits of the virtual card in their app.
  • In order to work with ApplePay, the terminal must be configured as an internet-based provider (web-enabled terminal).

[תמונה מעמוד 23: דוגמאות ממשק Apple Pay]

GooglePay

Activating the GooglePay digital wallet button from within the IFRAME.

				
					{
  "GooglePay": {
    "Enable": "true",
    "MerchantName": "Test"
  }
}

To embed in an IFRAME configuration, you must add the allowpaymentrequest attribute as shown in the example:

If you want to enable multiple buttons on a single Pelecard payment page (such as “כרטיס אשראי”, ApplePay, Google Pay), you can set GooglePay as the default button using the following parameter: "DefaultTabButton": "google_pay"

General Notes

  1. The parameters must be sent with the request to: https://gateway21.pelecard.biz/PaymentGW/init (including transaction amount, currency, etc.)
  2. GooglePay is supported on devices that support the Wallet app and have NFC capability. GooglePay also supported in any desktop (but not secured as in Wallet or NFC).
  3. It is not possible to generate a token-only transaction using J5 or J2 with GooglePay and then perform a recurring charge using the token. Supported options:
    • ActionType = J4 → Perform a direct charge
    • ActionType = J5 → Perform pre-authorization with the transaction amount and capture it later → Include: CreateToken = True The approval number and token created by Pelecard’s IFRAME are: ApprovalNo / DebitApproveNumber. Complete transaction options:
    • a. Via the Pelecard Reports system – https://reports.pelecard.biz,
      under the screen “איתור אישורים”
    • b. Via REST API – using one of the following methods: CompleteDebitByUid, DebitRegularType, DebitPaymentsType
    • c. Via Pelecard software installed on the merchant’s computer, integrated with a management system (e.g., Priority) Note about ActionType = J5: Merchants who already have a process for capturing pre-authorizations can use the same process with wallet transactions. As with non-wallet transactions, the approval number + Pelecard token should be used to finalize the charge. The exact same flow applies to wallet transactions.
  4. Wallet transactions are 3D Secure transactions.
  5. Refunds can be made using the Pelecard token received during a Google Pay transaction.
  6. Transactions can be located in the Pelecard Reports system (https://reports.pelecard.biz) using the last 4 digits of the virtual card (returned in the response), transaction amount, and date. The payer can find the virtual card number in their wallet app.
  7. Pelecard can activate Google Pay internally and eliminate the need for code implementation by the developer. In the INIT request for the IFRAME, send:
				
					{
  "GooglePay": {
    "Enable": "true",
    "MerchantName": "Test"
  }
}

Merchants who want to display a separate IFRAME with only the GooglePay button must include the following parameter in the INIT request:

				
					{
  "CreditCard": {
    "Enable": "false"
  }
}

Important to Know!

  • The card number returned from the transaction is a virtual card, not the customer’s real card.
  • If you want to investigate a transaction with the customer, ask them to check the last 4 digits of the virtual card in their wallet app.
  • To work with GooglePay, the terminal must be registered with an internet-based provider at the acquiring credit card company.

Paypal

This guide explains the principle of connecting to PayPal and the end-to-end process.

Purpose of the Pelecard-PayPal Interface

The purpose of the interface is to enable the customer to integrate and perform payments via PayPal. Since many users prefer not to leave their credit card details on websites or with companies they do not trust, many website owners have started using PayPal services.

The need to build a PayPal interface using Pelecard arises from the fact that website owners want to see in Pelecard reports that the transaction was completed and done through PayPal.

Step A – Initial Connection and General Process

  1. Redirecting to Payp.aspx returns a “Pay with PayPal” button.
    This redirect will pass all parameters related to the transaction.
  2. The user clicks the “Pay with PayPal” button and is redirected to PayPal to complete the payment.
  3. The website will receive a call to ValidateLink with the results of the action from PayPal via POST.
  4. After the payment is completed, the customer will be redirected to the URL specified in step 2.
    PayPal’s response will be sent via GET.
  5. The website must ensure that the transaction result is correct and the response is positive.
  6. A successfully completed transaction will also be recorded in Pelecard’s reporting system, indicating that the transaction was paid through PayPal.
  7. A transaction that failed will not be recorded in the reports.

Appendix 1 – Opening a SandBox Account

This guide will walk you through the steps to open a SandBox account on PayPal.

A PayPal SandBox account is a test account that allows you to perform tests for transactions on PayPal.

Note:
The SandBox account is for testing purposes only.
Transactions cannot be made using this account.

  1. Click on the following link: https://developer.paypal.com/
  2. Click “Log In” to sign in or “Sign Up” to register.
  3. Choose Program
  4. Put your Email and click next.
  5. Put your Phone number and click next with validation.
  6. Fill in the required details and click on “Create Account” at the bottom of the page.
  7. Start testing the system.

Good luck!

 

Appendix 2 – Paypal Error Codes

https://developer.paypal.com/docs/checkout/apm/reference/error-codes/