Google Pay Account Setup

General information

Google Pay™ is an electronic wallet system that allows you to make one-click payment using a card stored securely on Google side. There is no need to enter card details during Google Pay transaction.
Access to the payment mechanism is possible from any device, which supports Google Pay.
After choosing Google Pay payment method, the customer will see the form on which he confirms his Google account and card he is going to use to pay for order. If customer didn’t have a previously registered card, he may do it while making payment.

Terms of service

The following rules must be complied to use Google Pay:
The following rules must be complied to use Google Pay on websites:
The following rules must be complied to use Google Pay on mobile apps:

Google Pay Integration Overview

If accepting payments occurs in the Merchant`s app, Merchant must independently perform integration both with Mobilum and Google.
For integration with Google the following steps are required:
  1. Contact Mobilum support to get gateway, gatewayMerchantId and other test credentials required for Google Pay
  2. Integrate Google Pay. Detailed instructions from Google: https://developers.google.com/pay/api/android/overview
  3. Implement necessary payment methods (PAN_ONLY/CRYPTOGRAM_3DS)
  4. Perform internal testing of integration with Google and Mobilum payment gateway
  5. Pass acceptance tests and get production access to Google Pay
  6. Request live credentials from Mobilum support
  7. Replace test credentials with live and launch them on production

Google Pay - Google API Integration specifics

Google Pay Card Types

Merchant can independently choose the card types in Google Pay that will be available for payment. The card type is specified in the allowedAuthMethods Google request parameter.
There are two card types (authentication methods):
  1. PAN_ONLY (non-tokenized) - cards stored in customer`s Google account. These cards available on any device of the customer.
    The token contains the number and expiration date of the physical card. That is why 3-D Secure authentication is required for these cards. Read more in the Google Pay 3DS Processing section.
  2. CRYPTOGRAM_3DS (tokenized) - cards that are stored tokenized on the customer’s device. Tokenized cards are only available on the device where the card was added to the Google Pay app.
    The token contains the number and expiration date of the virtual card as well as the 3-D Secure cryptogram. Customer 3-D Secure verification for tokenized cards is not required.

Google Pay Card Networks

Mobilum Payment Gateway supports all networks specified in the allowedCardNetworks Google request parameter, such as: VISA, MASTERCARD, MIR, etc.

Google Pay 3DS Processing

Paying with Google Pay may require 3-D Secure authentication. 3DS is required for PAN_ONLY cards. It can be indicated by the Success==3DS in Google payment response.
3-D Secure authentication does not differ from the standard 3-D Secure.

Google Pay Web Integration

Google Pay Web Integration Overview

If accepting payments occurs on the Mobilum payment page, no additional integration with Google is required from the Merchant.
To use Google Pay on the Mobilum payment page, do the following:
  1. Enable Google Pay on the payment page template by adding macro
  2. Inform Mobilum support about the need to connect Google Pay and send updated templates
The Google Pay button will automatically appear on the Mobilum checkout page if:
  1. The customer uses the browser on a device that supports Google Pay
  2. The customer has Google Pay cards available for payment
The customer is on the Merchant’s website only until the moment of entering the data of his payment card or before paying with Google Pay.
For payment, the customer is redirected to the payment page on the Mobilum side.
After payment, the customer will be informed of the result and returned back to the Merchant’s website, and the Merchant will be sent notifications with the result of the payment.

Google Pay Web Transaction Flow

Customer -> Merchant: Checkout activate Merchant Merchant -> Mobilum: sale-form/ENDPOINTID activate Mobilum Mobilum -> Merchant: status=processing note right redirect-url end note deactivate Mobilum Merchant -> Customer: Provide **redirect-url** to customer browser deactivate Merchant activate Customer loop Merchant -> Mobilum: status/ENDPOINTID activate Mobilum activate Merchant Mobilum -> Merchant: status=processing deactivate Mobilum deactivate Merchant end Customer -> Customer: Press Google Pay button Customer -> "Google Pay": Submit Google Pay form deactivate Customer activate "Google Pay" "Google Pay" -> Mobilum: Card data deactivate "Google Pay" deactivate Customer activate Mobilum Mobilum -> Mobilum: Processing Mobilum -> Customer: Redirect to **redirect-url** deactivate Mobilum activate Customer Customer -> Merchant: Return to the Shop deactivate Customer activate Merchant alt **status** Merchant -> Mobilum: status/ENDPOINTID activate Mobilum Mobilum -> Merchant: Final status deactivate Mobilum else **callback** Mobilum -> Merchant: Callback with final status deactivate Merchant end

Merchant initiates a transaction by sending HTTPS POST request to the sale-form API URL and specifies the parameters according to sale-form Request Parameters.
Mobilum Server returns response described in sale-form response. Merchant than checks status repeatedly until he gets final status (approved/declined/filtered/error) or until he gets an HTML that should be sent directly to customer browser.
Merchant sends that html to customer’s browser causing customer to be redirected to Google Pay processor.
Customer hits processor page.
Processor bills an Google Pay invoice.
Customer pays invoice.
Processor notifies Mobilum that invoice is payed.
Mobilum makes a callback to Merchant using server_callback_url passed with the request.
Customer is returned to merchant site using redirect.

Google Pay Web Payment Form Integration

Google Pay button is supported only in sale-form integration on payment form in customer browser.
Payment Form integration is relevant for merchants who are not able to accept customer card details (merchant’s website must complete PCI DSS certification).
In case of Payment Form integration merchant is released of accepting payment details as handling of it is completely implemented on the Mobilum gateway side.
In addition, merchant may customize the look and feel of the Payment Form. Merchant must send the template to his/her Manager for approval before it could be used.

Payment Form API URL

For integration purposes use staging environment psandbox.mobilum.com instead of production pgate.mobilum.com. Payment Form transactions are initiated through HTTPS POST request by using URL in the following format:

Form Transaction by ENDPOINTID

The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.

https://pgate.mobilum.com/paynet/api/v2/sale-form/ENDPOINTID - for sale transactions
https://pgate.mobilum.com/paynet/api/v2/preauth-form/ENDPOINTID - for preauth transactions

Form Transaction by ENDPOINTGROUPID

The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.

https://pgate.mobilum.com/paynet/api/v2/sale-form/group/ENDPOINTGROUPID - for sale transactions
https://pgate.mobilum.com/paynet/api/v2/preauth-form/group/ENDPOINTGROUPID - for preauth transactions

Initiating a transaction with Payment Form

Merchant must supply the following parameters to initiate a sale transaction using payment form template.

Payment Form Request Parameters

Note

Request must have content-type=application/x-www-form-urlencoded.
Acquirer can redefine the necessity of some fields so they become mandatory instead of optional.
Leading and trailing whitespace in input parameters will be omitted.
Payment Form Request Example
client_orderid=902B4FF5
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100 Main st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=%2B12063582043
&cell_phone=%2B19023384543
&amount=10.42
&email=john.smith@gmail.com
&currency=USD
&ipaddress=65.153.12.232
&site_url=www.google.com
&purpose=user_account1
&redirect_url=http://pdoc.mobilum.com/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483
Payment Form Response Parameters

Note

Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
Response parameter name Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Order id assigned to the order by Mobilum
merchant-order-id Merchant order id
serial-number Unique number assigned by Mobilum server to particular request from the Merchant.
error-message If status is declined or error this parameter contains the reason for decline or error details
error-code The error code in case of declined or error status
redirect-url The URL to the page where the Merchant should redirect the client’s browser. Merchant should send HTTP 302 redirect, see General Payment Form Process Flow

Payment Form Response Example

type=async-response
&serial-number=00000000-0000-0000-0000-0000000624e8
&merchant-order-id=59e1e3ca-5d44-11e1-b3d6-002522b853b4
&paynet-order-id=94935&end-point-id=223
Payment Form final redirect

Upon completion of Payment Form process by the Customer he/she is automatically redirected to redirect_url. The redirection is performed as an HTTPS POST request with the parameters specified in the following table.

Redirect parameter name Description
status See Status List for details.
orderid Order id assigned to the order by Mobilum
merchant_order Merchant order id
client_orderid Merchant order id
error_message If status is declined or error this parameter contains the reason for decline or error details
control Checksum used to ensure that it is Mobilum (and not a fraudster) that initiates the request. This is SHA-1 checksum of the concatenation status + orderid + client_orderid + merchant-control.
descriptor Gate descriptor
processor-tx-id Acquirer transaction identifier
amount Actual transaction amount.
bin Bank BIN of customer credit card number
type The type of response.
card-type Type of customer credit card
phone Customer phone
last-four-digits Last four digits of customer credit card number
card-holder-name Cardholder name
error_code Error Code

If Merchant has passed server_callback_url in original Payment Form request Mobilum will call this URL. Merchant may use it for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. The parameters sent to this URL are specified in Callback Parameters.

Payment Form Template Sample
<html>
<head>
<script type="text/javascript">
  function isCCValid(r){var n=r.length;if(n>19||13>n)return!1;
    for(i=0,s=0,m=1,l=n;i<l;i++)d=parseInt(r.substring(l-i-1,l-i),10)*m,s+=d>=10?d%10+1:d,1==m?m++:m--;
    return s%10==0?!0:!1}
</script>
</head>
<body>
<h3>Order #$!MERCHANT_ORDER_ID - $!ORDERDESCRIPTION</h3>
<h3>Total amount: $!AMOUNT $!CURRENCY to $!MERCHANT</h3>

<form action="${ACTION}" method="post">
  <div>Cardholder name: <input name="${CARDHOLDER}" type="text" maxlength="64"/></div>
  <div><label for="cc-number">Credit Card Number</label> <input id="cc-number" name="${CARDNO}" type="text" maxlength="19" autocomplete="cc-number"/></div>
  <div>Card verification value: <input name="${CVV2}" type="text" maxlength="4" autocomplete="off"/></div>
  <div>
    Expiration date:
    <select class="expiry-month" name="${EXPMONTH}" size="1" autocomplete="cc-exp-month" >
      <option value="01">January</option><option value="02">February</option><option value="03">March</option>
      <option value="04">April</option><option value="05">May</option><option value="06">June</option>
      <option value="07">July</option><option value="08">August</option><option value="09">September</option>
      <option value="10">October</option><option value="11">November</option><option value="12">December</option>
    </select>
      <select class="expiry-year" id="cc-exp-year" name="${EXPYEAR}" size="1" autocomplete="cc-exp-year">
      ${EXPIRE_YEARS}
    </select>
  </div>
  <div>${GOOGLE_PAY}</div>
  $!{INTERNAL_SECTION}
  #if($!card_error)
  <div style="color: red;">$!card_error</div>
  #end
  <input name="submit" onclick="return isCCValid(document.getElementById('cardnumber').value);" type="submit" value="Pay"/>
</form>
</body>
</html>
Payment form macros
Field Name Macro Field Value Macro Description
${GOOGLE_PAY} n/a Google Pay buy button will be available if this macros is used.
${MERCHANT} n/a End point display name
${SKIN_VERSION} n/a CSS skin version
${ORDERDESCRIPTION} n/a Order description
${CUSTOMER_FIRST_NAME} n/a Customer first name sent by merchant via input parameters
${CUSTOMER_LAST_NAME} n/a Customer last name sent by merchant via input parameters
${CUSTOMER_EMAIL} n/a Customer E-mail address sent by merchant via input parameters
${AMOUNT} n/a Amount
${CURRENCY} n/a Currency
${PAYNET_ORDER_ID} n/a Mobilum order id
${MERCHANT_ORDER_ID} n/a Merchant order id
${refresh_interval} n/a Refresh interval recommended by system
${uuid} n/a Internal
${INTERNAL_SECTION} n/a Internal for iFrame integration
${CUSTOMER_IP_COUNTRY_ISO_CODE} n/a Customer country defined by IP Address
${PREFERRED_LANGUAGE} n/a Customer language sent by merchant via input parameters
${MERCHANT_FORM_DATA} n/a Parameters sent in merchant_form_data API parameter are parsed into macros with the same name, the parameter is url-encoded, example: testparam%3Dtest1%26mynewparam%3Dtest2 and is parsed into $MFD_testparam = test1 and $MFD_mynewparam = test2 macros in the form. Parameter name characters[a-zA-Z0-9], parameter value characters[a-zA-Z0-9], control characters [=&], 2MB max size. For example, this parameter can be used to display payment form in light/dark mode depending on the value passed by Connecting Party (e.g. pass merchant_form_data=theme%3Ddark in request and $MFD_theme macro placeholder on payment form will be changed to dark.
${CUSTOMER_ZIP_CODE} n/a Generates a ZIP code to send to the processor if it was not received from the client
Wait Page Template Sample
<html>
<head>
<script type="text/javascript">
  function fc(t) {
    document.getElementById("seconds-remaining").innerHTML = t;
    (t > 0) ? setTimeout(function(){fc(--t);}, 1000) : document.checkform.submit();}
</script>
</head>
<body onload="fc($!refresh_interval)">
<h3>Order #$!MERCHANT_ORDER_ID - $!ORDERDESCRIPTION</h3>
<h3>Total amount: $!AMOUNT $!CURRENCY to $!MERCHANT</h3>
Please wait, your payment is being processed, remaining <span id="seconds-remaining">&nbsp;</span> seconds.
<form name="checkform" method="post">
  <input type="hidden" name="tmp" value="$!uuid"/>
      $!{INTERNAL_SECTION}
  <input type="submit" value="Check" />
</form>
</body>
</html>
Wait Page macros
Field Name Macro Field Value Macro Description
${MERCHANT} n/a End point display name
${SKIN_VERSION} n/a CSS skin version
${ORDERDESCRIPTION} n/a Order description
${AMOUNT} n/a Amount
${CURRENCY} n/a Currency
${PAYNET_ORDER_ID} n/a Mobilum order id
${MERCHANT_ORDER_ID} n/a Merchant order id
${refresh_interval} n/a Refresh interval recommended by system
${uuid} n/a Internal
${INTERNAL_SECTION} n/a Internal for iFrame integration
${CUSTOMER_IP_COUNTRY_ISO_CODE} n/a Customer country defined by IP Address
${PREFERRED_LANGUAGE} n/a Customer language send by merchant via input parameters
${BROWSER_LANGUAGE} n/a Customer language defined by browser settings
${CUSTOMER_LANGUAGE} n/a Customer language send by merchant via input parameters or defined by browser settings if first is not set
Finish Page Macros
Field Name Macro Field Value Macro Description
${STATUS} n/a Order status
${PAYNET_ORDER_ID} n/a System order id
${MERCHANT_ORDER_ID} n/a Merchant order id
${ERROR_MESSAGE} n/a Contains the reason for decline or error details
${SKIN_VERSION} n/a CSS skin version
${CUSTOMER_IP_COUNTRY_ISO_CODE} n/a Customer country defined by IP Address
${PREFERRED_LANGUAGE} n/a Customer language send by merchant via input parameters
${BROWSER_LANGUAGE} n/a Customer language defined by browser settings
${CUSTOMER_LANGUAGE} n/a Customer language send by merchant via input parameters or defined by browser settings if first is not set
${AMOUNT} n/a Amount
${CURRENCY} n/a Currency
${DESCRIPTION} n/a Transaction description
${DATE} n/a Transaction date
${PAYNET_PROCESSING_DATE} n/a Paynet processing date
${RRN} n/a Reference Retrieval Number
${AUTH_CODE} n/a Authorization Code

Request authorization through control parameter

The checksum is used to ensure that it is a particular Merchant (and not a fraudster) that initiates the transaction. This SHA-1 checksum, the parameter control, is created by concatenation of the parameters values in the following order:

  • ENDPOINTID/ENDPOINTGROUPID
  • client_orderid
  • minimal monetary units amount (i.e. cent, penny etc. For amount 0.94 USD value in signing string will be 94, for 10.15 USD value in signing string will be 1015)
  • email
  • merchant_control

A complete string example may look as follows:

59I6email@client.com3E8E45B5-2-42D8-6ECC-FBF6B11B1

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter (see Payment Form Request Parameters) which is required for request authorization. For the above-mentioned example the control will take the following value:

d02e67236575a8e02dea5e094f3c8f12f0db43d7

Payment Form Request Debug
endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
client_orderid make it or use your internal invoice ID
order_desc
first_name
last_name
ssn
birthday
address1
city
state
zip_code
country
phone
cell_phone
amount ​
email
currency
ipaddress
site_url
purpose
merchant_control input your Control Key
redirect_url
redirect_success_url
redirect_fail_url
server_callback_url
merchant_data
cardrefid
maximum-transaction-amount
minimum-transaction-amount
merchant_form_data

String to sign
Signature

Google Pay Web Order Status

Merchant must use Order status API call to get the customer’s order transaction status. After any type of transaction is sent to Mobilum server and order id is returned, Merchant should poll for transaction status. When transaction is processed on Mobilum server side it returns it’s status back to Merchant and at this moment the Merchant is ready to show the customer transaction result, whether it’s approved or declined.

Status API URL

For integration purposes use staging environment psandbox.mobilum.com instead of production pgate.mobilum.com. Status API calls are initiated through HTTPS POST request by using URL in the following format:

The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://pgate.mobilum.com/paynet/api/v2/status/ENDPOINTID
The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.
https://pgate.mobilum.com/paynet/api/v2/status/group/ENDPOINTGROUPID

Order status call parameters

Note

Request must have content-type=application/x-www-form-urlencoded.
Status Call Parameter Description Necessity
login Merchant login name Mandatory
client_orderid Merchant order identifier of the transaction for which the status is requested Mandatory
orderid Order id assigned to the order by Mobilum Conditional
control Checksum used to ensure that it is Mobilum (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control. See Order status API call authorization through control parameter for more details about generating control checksum. Mandatory
by-request-sn Serial number assigned to the specific request by Mobilum. If this field exist in status request, status response return for this specific request. Include this parameter to get the status response with the particular transaction stage (can be used in specific cases). To get the latest transaction status, don’t include this parameter in status request. Optional
In most common cases, the best option is to include both client_orderid and orderid parameters to status request. Order status can be requested with only client_orderid if it’s unique to merchant and orderid is not received. If orderid is not received in response, but this response contains an error, see the received error message to get the information why transaction was not created in the system.

Order Status Response

Note

Response has Content-Type: text/html;charset=utf-8 header. All parameters in response are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value
Status Response Parameter Description
type The type of response. May be status-response
status See Status List for details.
amount Actual transaction amount. This value can be changed during the transaction flow.
currency Currency of the initial transaction.
paynet-order-id Order id assigned to the order by Mobilum
merchant-order-id Merchant order id
phone Customer phone.
serial-number Unique number assigned by Mobilum server to particular request from the Merchant.
last-four-digits Last four digits of customer credit card number.
bin Bank BIN of customer credit card number.
card-type Type of customer credit card (VISA, MASTERCARD, etc).
gate-partial-reversal Processing gate support partial reversal (enabled or disabled).
gate-partial-capture Processing gate support partial capture (enabled or disabled).
transaction-type Transaction type (sale, reversal, capture, preauth).
processor-rrn Bank Receiver Registration Number.
processor-tx-id Acquirer transaction identifier.
receipt-id Electronic link to receipt https://pgate.mobilum.com/paynet/view-receipt/ENDPOINTID/receipt-id/
cardholder-name Cardholder name.
card-exp-month Card expiration month.
card-exp-year Card expiration year.
card-hash-id Unique card identifier to use for loyalty programs or fraud checks.
card-country-alpha-three-code Three letter country code of source card issuer. See Country Codes for details
email Customer e-mail.
purpose Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +7123456789; gamer0001@ereality.com etc. This value will be used by fraud monitoring system.
bank-name Bank name by customer card BIN.
terminal-id Acquirer terminal identifier to show in receipt.
paynet-processing-date Acquirer transaction processing date.
approval-code Bank approval code.
order-stage The current stage of the transaction processing. See Order Stage for details.
loyalty-balance The current bonuses balance of the loyalty program for current operation. if available
loyalty-message The message from the loyalty program. if available
loyalty-bonus The bonus value of the loyalty program for current operation. if available
loyalty-program The name of the loyalty program for current operation. if available
descriptor Bank identifier of the payment recipient.
original-gate-descriptor Descriptor, which is set on gate level in the system.
error-message If status in declined, error, filtered this parameter contains the reason for decline
error-code The error code is case status in declined, error, filtered.
by-request-sn Serial number assigned to the specific request by Mobilum. If this field exist in status request, status response return for this specific request.
verified-3d-status See 3-D Secure Status List for details
eci Electronic Commerce Indicator (Visa).
ips-src-payment-product-code Code for card set by multinational financial service. (Visa/Mastercard).
ips-src-payment-product-name Decrypted code for card set by multinational financial service. (Visa/Mastercard).
ips-src-payment-type-code Type of card code set by multinational financial service. (Visa/Mastercard).
ips-src-payment-type-name Decrypted code for type of card set by multinational financial service. (Visa/Mastercard)
initial-amount Amount, set in initiating transaction, without any fees or commissions. This value can’t change during the transaction flow.
seller-commission Total commission for processed transaction. This is optional parameter. Please contact your manager in Mobilum, if you would like to receive it.
acquirer-commission Acquirer commission for processed transaction. This is optional parameter. Please contact your manager in Mobilum, if you would like to receive it.
transaction-date Date of final status assignment for transaction.

Order Status Response Example

type=status-response
&serial-number=00000000-0000-0000-0000-0000005b5eec
&merchant-order-id=6132tc
&processor-tx-id=9568-47ed-912d-3a1067ae1d22
&paynet-order-id=161944
&status=approved
&amount=7.56
&descriptor=no
&original-gate-descriptor=test 12345678 3Ds Bank
&gate-partial-reversal=enabled
&gate-partial-capture=enabled
&transaction-type=cancel
&receipt-id=2050-3c93-a061-8a19b6c0068f
&name=FirstName
&cardholder-name=FirstName
&card-exp-month=3
&card-exp-year=2028
&email=no
&processor-rrn=510458047886
&approval-code=380424
&order-stage=cancel_approved
&last-four-digits=1111
&bin=444455
&card-type=VISA
&phone=%2B79685787194
&bank-name=UNKNOWN
&paynet-processing-date=2015-04-14+10%3A23%3A34+MSK
&by-request-sn=00000000-0000-0000-0000-0000005b5ece
&card-hash-id=1569311
&card-country-alpha-three-code=RUS
&verified-3d-status=AUTHENTICATED
&eci=02
&ips-src-payment-product-code=SAP
&ips-src-payment-product-name=SAP—Platinum Mastercard® Salary– Immediate Debit
&ips-src-payment-type-code=Debit
&ips-src-payment-type-name=MASTERCARD Debit
&initial-amount=7.56
&transaction-date=2023-01-10+12%3A46%3A28+MSK

Status request authorization through control parameter

The checksum is used to ensure that it is Merchant (and not a fraudster) that sends the request to Mobilum. This SHA-1 checksum, the parameter control, is created by concatenating of the values of the parameters in the following order:

  • login
  • client_orderid
  • orderid
  • merchant_control

For example assume the following values are corresponds the parameters above:

Parameter Name Parameter Value
login cool_merchant
client_orderid 5624444333322221111110
orderid 9625
merchant_control r45a019070772d1c4c2b503bbdc0fa22

The complete string example may look as follows:

cool_merchant56244443333222211111109625r45a019070772d1c4c2b503bbdc0fa22

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter which is required for authorizing the callback. For the example control above will take the following value:

c52cfb609f20a3677eb280cc4709278ea8f7024c

Order status Debug

endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
login
client_orderid input your Invoice Number
orderid
merchant_control input your Control Key
by-request-sn

String to sign
Signature

Google Pay Android Integration

Google Pay Android - Integration to Mobilum

General Sale Process Flow

Application initiates a transaction by sending HTTPS POST request to the specified URL

Mobilum server immediately returns the response back to Application. The response contains paynet-order-id. For detailed request and response format see mapi-req <MAPI Sale Request Parameter>.

Application shows the Customer message like Your order is being processed. Please, wait…. Application starts polling Mobilum server for transaction status using paynet-order-id obtained at previous step. Status polling request and response are described in Order status asynchronous call

Sale transaction diagram

The Application should use Mobilum API as described in General Sale Process Flow.

Merchant -> "Mobilum": Sale request activate "Mobilum" "Mobilum" --> Merchant: Order ID "Mobilum" -> Acquirer: Process sale activate Acquirer Merchant -> "Mobilum": Get status by Order ID Acquirer --> "Mobilum": Processing result deactivate Acquirer "Mobilum" --> Merchant: Final status deactivate "Mobilum"

Sale request Customer checks out the order and Application sends Sale request to Mobilum server with specified parameters described in Sale Request Parameters.
Order Id Mobilum server sends back the response with orderid. Application shows the customer a message like Your order is being processed. Please, wait… and starts polling for status with given orderid as described in Order status asynchronous call.
Process Sale Mobilum server forwards Sale request to bank acquirer asynchronously. The bank starts processing the transaction.
Get status by Order Id Application is polling for status with given orderid as described in Order status asynchronous call.
Sale approved or declined The bank responds to Mobilum server with approve or decline for requested Sale
Return Status – approved or declined Mobilum server returns status to Application through Order status asynchronous call.

Process Sale transaction

In order to initiate a Sale transaction via device, Application sends an HTTPS POST request with the parameters specified in MAPI Sale Request Parameters Table below

MAPI Sale Request Parameter Length/Type Comment Necessity*
client_orderid 128/String Merchant order identifier. Mandatory
order_desc 64k/String Brief order description Mandatory
first_name 50/String Customer’s first name Optional
last_name 50/String Customer’s last name Optional
ssn 32/Numeric Last four digits of the customer’s social security number. Optional
birthday 8/Numeric Customer’s date of birth, in the format MMDDYY. Optional
address1 50/String Customer’s address line 1. Mandatory
city 50/String Customer’s city. Mandatory
state 2-3/String Customer’s state . Please see Reference for a list of valid state codes. Mandatory for USA, Canada and Australia. Optional
zip_code 10/String Customer’s ZIP code Mandatory
country 2/String Customer’s country(two-letter country code). Please see Reference for a list of valid country codes. Mandatory
phone 15/String Customer’s full international phone number, including country code. Optional
cell_phone 15/String Customer’s full international cell phone number, including country code. Optional
email 50/String Customer’s email address. Mandatory
amount 10/Numeric Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents Mandatory
currency 3/String Currency the transaction is charged in (three-letter currency code). Sample values are: USD for US Dollar EUR for European Euro Mandatory
cvv2 3-4/Numeric Customer’s CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number AFTER the credit card number in the signature area of the card. It used if acquirer provides only E-Commerce connection. Optional
ipaddress 45/String Customer’s IP address, included for fraud screening purposes. Mandatory
purpose 128/String Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +7123456789; gamer0001@ereality.com etc. This value will be used by fraud monitoring system. Optional
server_callback_url 1024/String URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. See more details at Merchant Callbacks Optional
encrypted-type 32/String Type of the encryption. This depends on device model. Mandatory
encrypted-data String Card tracks data encrypted using encrypted-type encryption and encoded using HEX encoding. For more info contact support. Mandatory
* leading and trailing whitespace in input parameters will be omitted

Please note the following characters must be escaped in the parameter values: & + \.

Sale Request Example

client_orderid=123098
&cvv2=XXX
&amount=114.94
&ipaddress=115.135.52.242
&state=
&currency=USD
&phone=+6072344354
&zip_code=81200
&order_desc=Super product 1
&email=francislusaikun@yahoo.com
&country=MY
&city=Johor Bahru
&address1=11Jalan Lurah 6 Kg. Kempas Baru
&redirect_url=http://MERCHANT_SITE/payment_update/123098/
&encrypted-type=algo-name
&encrypted-data=D0902DD0B02120D09220D090D184D180D0B8D0BAD0B520D180D0B5D0BAD0B820D0B2D0BED18220D18
                2D0B0D0BAD0BED0B920D188D0B8D180D0B8D0BDD18B210AD0902DD0B02120D09220D090D184D180D0
                B8D0BAD0B520D0B3D0BED180D18B20D0B2D0BED18220D182D0B0D0BAD0BED0B920D0B2D18BD188D0B
                8D0BDD18B210AD0902DD0B02C20D0BAD180D0BED0BAD0BED0B4D0B8D0BBD18B2DD0B1D0B5D0B3D0B5
                D0BCD0BED182D18B2C0AD0902DD0B02C20D0BED0B1D0B5D0B7D18CD18FD0BDD18B2DD0BAD0B0D188D
                0B0D0BBD0BED182D18B2C0AD0902DD0B02C20D0B820D0B7D0B5D0BBD191D0BDD18BD0B920D0BFD0BE
                D0BFD183D0B3D0B0D0B921

Sale Response

Sale Response Parameter Description
type The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
status See Status List for details.
paynet-order-id Order id assigned to the order by Mobilum
merchant-order-id Merchant order id
serial-number Unique number assigned by Mobilum server to particular request from the Merchant.
error-message If status is error this parameter contains the reason for decline or error details
error-code The error code is case of error status

Sale Response Example

type=async-response
&serial-number=00000000-0000-0000-0000-0000000624e8
&merchant-order-id=59e1e3ca-5d44-11e1-b3d6-002522b853b4
&paynet-order-id=94935

Server callback result

Upon completion by the System of request processing it returns the result on the specified server_callback_url with the following parameters described in Callback Parameters. The checksum is used to ensure that the callback is initiated for a particular Merchant, and not for anybody else claiming to be such Merchant. This SHA-1 checksum, the control parameter, is created by concatenation of the parameters values in the following order:

  • status
  • orderid
  • client_orderid
  • merchant_control

A complete string example may look as follows:

approvedS279G323P4T1209294c258d6536ababe653E8E45B5-7682-42D8-6ECC-FB794F6B11B1

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter. For the above-mentioned example the control will take the following value:

e04bd50531f45f9fc76917ac78a82f3efaf0049c

All parameters are sent via GET method.

Server callback result example
status=declined
&error-message=Decline, refer to card issuer
&error-code=107
&paynet-order-id=S279G323P4T1209294
&merchant-order-id=c258d6536ababe65

Request authorization through OAuth signature

To make sure that it’s the Merchant (and not somebody else) is who really authors requests, requests must be signed. OAuth 1.0a signature is used as a well-established and supported in the client libraries for this purpose on MAPI requests. Please note that it’s the only part of OAuth that we use in our API: signatures; our API does not actually support a full-blown OAuth. Both RSA-SHA1 and HMAC-SHA1 methods may be used to generate signatures.

Request signing with RSA-SHA1 signature method

This signature method is only available if MAPI was registered with RSA public key. No shared secret is needed. Merchant just uses his private key to sign requests. Reader serial number is used as an API token. Here is an example of how to make a signed request in Java with help of scribe library:

public String doPost(String url, Map<String, String> parameters) throws ConnectionIOException, ConnectionTimeoutException
{
    OAuthConfig config = new OAuthConfig(apiToken, merchantControlKey, OAuthConstants.OUT_OF_BAND, SignatureType.Header, null,null);
    OAuthService service = new OAuth10aServiceImpl(new HmacSha1Mapi(), config);
    OAuthRequest request = new OAuthRequest(Verb.POST, url);
    for (Map.Entry<String, String> entry : parameters.entrySet()) {
        request.addBodyParameter(entry.getKey(), entry.getValue());
    }
    // empty token for 'two-legged'
    OAuth Token token = new Token("", "");
    service.signRequest(token, request);
    Response response = request.send();
    return response.getBody();
}

private static class Mapi extends DefaultApi {
    @Override
    public String getRequestTokenEndpoint() {
        return null;
    }

    @Override
    public String getAccessTokenEndpoint() {
        return null;
    }

    @Override
    public String getAuthorizationUrl(Token requestToken) {
        return null;
    }

    @Override
    public SignatureService getSignatureService() {
        return new HMACSha1SignatureService();
    }
}
Request signing with HMAC-SHA1 signature method

This signature method is always available even for MAPI registered without a public key. Merchant control key is used as a secret key. Reader serial number is used as an API token. Here is an example of how to make a signed request in Java with help of scribe library:

public String doPost(String url, Map<String, String>parameters) throws ConnectionIOException, ConnectionTimeoutException {
        OAuthConfig config = new OAuthConfig(apiToken, merchantControlKey, OAuthConstants.OUT_OF_BAND,
                SignatureType.Header, null,null);
        OAuthService service = new OAuth10aServiceImpl(new HmacSha1Mapi(), config);
        OAuthRequest request = new OAuthRequest(Verb.POST,url);
        for (Map.Entry < String,String >;entry :parameters.entrySet()){
            request.addBodyParameter(entry.getKey(), entry.getValue());
        } // empty token for 'two-legged'
        OAuth Token token = new Token("", "");
        service.signRequest(token, request);
        Response response = request.send();
        return response.getBody();
    }

    private static class Mapi extends DefaultApi {
        @Override
        public String getRequestTokenEndpoint() {
            return null; // not used
        } @Override public String getAccessTokenEndpoint() {
            return null; //not used
        }

        @Override
        public String getAuthorizationUrl(Token requestToken) {
            return null; // not used
        }
        @Override
        public SignatureService getSignatureService() {
            return new HMACSha1SignatureService();
        }
    }

Google Pay Android Order status

Application must use Order status API call to get the customer’s order transaction status. After any type of transaction is sent to Mobilum server and order id is returned, Application should poll for transaction status. When transaction is processed on Mobilum server side it returns it’s status back to Application and at this moment the Application is ready to show the customer transaction result, whether it’s approved or declined.

Status API URL

Status API calls are initiated through HTTPS POST request by using URL in the following format:
https://pgate.mobilum.com/paynet/api/v2/status/ENDPOINTID
for integration purposes use staging environment psandbox.mobilum.com instead of production pgate.mobilum.com

The End point ID is an entry point for incoming Merchant’s transactions and is actually the only Mobilum object which is exposed via API.

Order status call parameters

Status call Parameter Description
login Merchant login name
client_orderid Merchant order identifier of the transaction for which the status is requested
orderid Order id assigned to the order by Mobilum
control Checksum used to ensure that it is Mobilum (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control. See Order status API call authorization through control parameter for more details about generating control checksum.

Order Status Response

Status Response Parameter Description
type The type of response. May be status-response
status See Status List for details.
paynet-order-id Order id assigned to the order by Mobilum
merchant-order-id Merchant order id
phone Customer phone.
amount Initial transaction amount.
serial-number Unique number assigned by Mobilum server to particular request from the Merchant.
last-four-digits Last four digits of customer credit card number.
bin Bank BIN of customer credit card number.
card-type Type of customer credit card (VISA, MASTERCARD, etc).
gate-partial-reversal Processing gate support partial reversal (enabled or disabled).
gate-partial-capture Processing gate support partial capture (enabled or disabled).
transaction-type Transaction type (sale, reversal, capture, preauth).
processor-rrn Bank Receiver Registration Number.
processor-tx-id Acquirer transaction identifier.
receipt-id Electronic link to receipt https://pgate.mobilum.com/paynet/view-receipt/ENDPOINTID/receipt-id/
cardholder-name Cardholder name.
card-exp-month Card expiration month.
card-exp-year Card expiration year.
card-hash-id Unique card identifier to use for loyalty programs or fraud checks.
email Customer e-mail.
bank-name Bank name by customer card BIN.
terminal-id Acquirer terminal identifier to show in receipt.
paynet-processing-date Acquirer transaction processing date.
approval-code Bank approval code.
order-stage The current stage of the transaction processing. See Order Stage for details
loyalty-balance The current bonuses balance of the loyalty program for current operation. if available
loyalty-message The message from the loyalty program. if available
loyalty-bonus The bonus value of the loyalty program for current operation. if available
loyalty-program The name of the loyalty program for current operation. if available
descriptor Bank identifier of the payment recipient.
error-message If status in declined, error, filtered this parameter contains the reason for decline
error-code The error code is case status in declined, error, filtered.
verified-3d-status See 3-D Secure Status List for details
verified-rsc-status See Random Sum Check Status List for details
transaction-date Date of final status assignment for transaction.

Order Status Response Example

type=status-response
&serial-number=00000000-0000-0000-0000-0000005b5ecf
&merchant-order-id=006349-000117
&processor-tx-id=PNTEST-158258
&paynet-order-id=158258
&status=approved
&amount=1.00
&descriptor=WORLD+ORDER+AG
&gate-partial-reversal=enabled
&gate-partial-capture=enabled
&transaction-type=sale
&receipt-id=e876012c-d94e-3462-8e2e-a1bb4cb30633
&name=PKMVC%2FUNEMBOSSED
&cardholder-name=PKMVC%2FUNEMBOSSED
&card-exp-month=10
&card-exp-year=2015
&email=no-email
&processor-rrn=509275795375
&approval-code=378906
&order-stage=sale_approved
&last-four-digits=0985
&bin=462783
&card-type=VISA
&bank-name=MOSCOMPRIVATBANK+%28MOSCOW+COMMERCIAL+BANK%29
&terminal-id=12345678
&paynet-processing-date=2015-04-02+20%3A36%3A20+MSK
&card-hash-id=1575636
&verified-3d-status=AUTHENTICATED
&verified-rsc-status=AUTHENTICATED
&transaction-date=2023-01-10+12%3A46%3A28+MSK

Status request authorization through control parameter

The checksum is used to ensure that it is Merchant (and not a fraudster) that sends the request to Mobilum. This SHA-1 checksum, the parameter control, is created by concatenating of the values of the parameters in the following order:

  • login
  • client_orderid
  • orderid
  • merchant_control

For example assume the following values are corresponds the parameters above:

Parameter Name< Parameter Value
login cool_merchant
client_orderid 5624444333322221111110
orderid 9625
merchant_control r45a019070772d1c4c2b503bbdc0fa22

The complete string example may look as follows:

cool_merchant56244443333222211111109625r45a019070772d1c4c2b503bbdc0fa22

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter which is required for authorizing the callback. For the example control above will take the following value:

c52cfb609f20a3677eb280cc4709278ea8f7024c

Order status Debug

endpointid input your ENDPOINTID
login
client_orderid input your Invoice Number
orderid
merchant_control input your Control Key
by-request-sn

String to sign
Signature