MuchBetter deposit

Payment Methods offered by MuchBetter are mobile-only solution available on both IOS and Android platforms.

Paying a merchant involves 2 simple steps:

  1. Customer enters their phone number on merchant site.
  2. Customer authorises payment via the MuchBetter app on their phone.

Customers may also receive money from merchants and top up funds (via a number of methods such as credit/debit cards, bank transfers, cash etc.).

The following method IDs are covered in this section:

ID

Name

Credit/Debit State

318

MuchBetterDeposit

DepositedByProvider (29)

Payment method interaction type: Redirection to External Payment Provider (see Interaction Types).

There are two possible paths:

Customer has MuchBetter account

  1. Customer initiates a payment via MuchBetter
  2. Merchant send to PXP Financial initiatePaymentRequest with phone number which is registered on MuchBetter
  3. PXP Financial sends initiatePaymentRequest to MuchBetter
  4. PXP Financial receives initiatePaymentResponse
  5. Merchant receives initiatePaymentResponse
  6. Customer authorises transaction via MuchBetter mobile app
  7. MuchBetter sends notification to PXP Financial
  8. PXP Financial sends PaymentStateChangedNotification to Merchant

or

Customer doesn't have MuchBetter account

  1. Customer initiates a payment via MuchBetter
  2. Merchant sends to PXP Financial initiatePaymentRequest with a phone number which is NOT registered on MuchBetter
  3. PXP Financial sends initiatePaymentRequest to MuchBetter
  4. PXP Financial receives initiatePaymentResponse with customerAccountStatus: "INCOMPLETE"
  5. PXP Financial composes the Quick Sign up URL (redirect URL) and send it to Merchant
  6. Merchant exposes the Quick Sign up URL (redirect URL) to the customer
  7. Customer signs up to MuchBetter and downloads the MuchBetter app
  8. Customer confirms the transaction
  9. MuchBetter sends notification to PXP Financial
  10. PXP Financial sends PaymentStateChangedNotification to Merchant

Sequence diagram

Following diagram describes MuchBetter deposit

761761

Testing information

For testing transaction in the PXP Financial payment service TEST1 merchants need to send the call initiatePayment as detailed below, then fetch the MuchBetter app to approve the payment.

Test Android apps are available here: https://betas.to/iz42oegp

The test apps are currently only available for Android. The production apps are available for IOS and Android.

Please create your own test accounts using a valid phone number. Choose address country same as phone country. If you see something unusual , you may have triggered security alerts, so contact PXP Financial or MuchBetter.

Once your account is created, you can fund it, by making withdrawal from your test merchant API key. And use those funds for testing deposit. The balance is shown in the app.

The phone number should be provided in the form 447624111111 where 44 is country code and 7624111111 is mobile number including area code with no leading 0.

The passcode is any 4 digit pass code. The one time code is sent by SMS - in the sandbox it´s always 000000 and you will NOT get a one time code.

Backend2Backend Integration

The following table contains the fields to be sent in the initiatePaymentRequest xml section:

key (value type, account type, required)

value

amount
(decimal, required)

Deposit amount. Must be numeric value

The following parameters can be provided in initiatePaymentRequest.userData:

key (value type, account type, required)

value

username (string, optional)

Username

firstname (string, optional)

User's first name

lastname (string, optional)

User's last name

dateOfBirth (string, optional)

User's date of birth in following format: YYYYMMDD

email (string, optional)

User's email address

countryCode2 (string, optional)

User's address parameter (2 letters country code)

postalCode (string, optional)

User's address parameter (zip code)

city (string, optional)

User's address parameter (City)

currencyCode (string, optional)

User's account currency. Supported currencies are: EUR, GBP and USD

languageCode (string, optional)

User's preferred language (2 letters language code)

The following parameters can be provided in initiatePaymentRequest.specificPaymentData:

key (value type, account type, required)

value

PaymentDescription (string, required)

Billing descriptor up to 120 chars. Transaction reference which will be displayed to the customer.

PaymentDescriptionLanguageCode (string, required)

Language code for the payment description

brandName (string, optional)

Used to decide which logo to show customer in the App

The following parameters can be provided in initiatePaymentRequest.specificPaymentAccountData:

key (value type, account type, required)

value

AccountNumber (string, required)

User’s phone number in international format without "+" or "00". E.g. 447624222721 - 44 is country code and 7624222721 is phone number. The key parameter of a MuchBetter user account.

Scenario: Successful Payment

Example initiatePaymentRequest for a registered phone number (447624222722):

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
    <merchantID>KalixaAcceptDemo</merchantID>
    <shopID>KalixaAcceptDemo</shopID>
    <merchantTransactionID>42e9-94df-1213dd-h344hyhj5w4-23.11.2018-007</merchantTransactionID>
    <paymentMethodID>318</paymentMethodID>
    <amount currencyCode="EUR">1.11</amount>
    <userID>6895456</userID>
    <userIP>127.0.0.1</userIP>
    <userSessionID>7c3a5a67-2034-446a-b073-aedb75d9b8d7</userSessionID>
    <creationTypeID>1</creationTypeID>
    <specificPaymentData>
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescription</key>
            <value>test desc</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescriptionLanguageCode</key>
            <value>EN</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>BrandName</key>
            <value>Kalixa</value>
        </data>
    </specificPaymentData>
    <paymentAccount>
        <specificPaymentAccountData>
            <data xsi:type="keyStringValuePair">
                <key>AccountNumber</key>
                <value>447624222722</value>
            </data>
        </specificPaymentAccountData>
    </paymentAccount>
</initiatePaymentRequest>

Example initiatePaymentResponse in case of registered customer:

<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>KalixaAcceptDemo</merchantID>
        <shopID>KalixaAcceptDemo</shopID>
        <paymentMethod>
            <key>318</key>
            <value>MuchBetterDeposit</value>
        </paymentMethod>
        <merchantTransactionID>42e9-94df-1213dd-h344hyhj5w4-23.11.2018-002</merchantTransactionID>
        <paymentID>3f015b20-8227-4401-b0f9-0c6db094530d</paymentID>
        <userID>6895456</userID>
        <paymentProvider>
            <key>176</key>
            <value>MuchBetter</value>
        </paymentProvider>
        <amount currencyCode="EUR">1.11</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>35b02d16-9a29-4cec-b81c-1ddb409de194</id>
            <definition>
                <key>3</key>
                <value>InitiatedByProvider</value>
            </definition>
            <createdOn>2018-11-23T08:19:54.0577897Z</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseCode</key>
                    <value>PENDING_SENDER_APPROVAL</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">1.11</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>161196</value>
            </detail>
            <detail xsi:type="keyBooleanValuePair">
                <key>IsCustomerDOBMatchedAtProvider</key>
                <value>false</value>
            </detail>
            <detail xsi:type="keyBooleanValuePair">
                <key>IsCustomerCountryMatchedAtProvider</key>
                <value>false</value>
            </detail>
            <detail xsi:type="keyBooleanValuePair">
                <key>IsCustomerLastNameMatchedAtProvider</key>
                <value>false</value>
            </detail>
            <detail xsi:type="keyBooleanValuePair">
                <key>IsCustomerRegisteredAtProvider</key>
                <value>true</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>1898407</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>7c60503e-25e6-4b30-86cf-9084dcb64041</paymentAccountID>
        </paymentAccount>
    </payment>
</initiatePaymentResponse>

Scenario: Unsuccessful Payment

Example initiatePaymentResponse in case of non yet registered customer (phone number 447624222723):

<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>KalixaAcceptDemo</merchantID>
        <shopID>KalixaAcceptDemo</shopID>
        <paymentMethod>
            <key>318</key>
            <value>MuchBetterDeposit</value>
        </paymentMethod>
        <merchantTransactionID>42e9-94df-1213dd-h344hyhj5w4-23.11.2018-004</merchantTransactionID>
        <paymentID>78eff428-9d85-46f6-a256-d357d9105f3b</paymentID>
        <userID>6895456</userID>
        <paymentProvider>
            <key>176</key>
            <value>MuchBetter</value>
        </paymentProvider>
        <amount currencyCode="EUR">1.11</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>d8be387d-40f4-434a-b92f-003ff832f04f</id>
            <definition>
                <key>30</key>
                <value>RedirectURLCreated</value>
            </definition>
            <createdOn>2018-11-23T08:30:00.0651689Z</createdOn>
            <description>https://d2a.d.goodlpay.com/merchant/user?trackingCode=1x13&amp;currency=EUR&amp;email=John.DeDoe%40test.at&amp;firstname=John&amp;lastname=De%20Doe&amp;dobYYYYMMDD=00010101&amp;address1=&amp;zipcode=&amp;phonenumber=447624222723&amp;city=&amp;country=</description>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>RedirectionUrl</key>
                    <value>https://d2a.d.goodlpay.com/merchant/user?trackingCode=1x13&amp;currency=EUR&amp;email=John.DeDoe%40test.at&amp;firstname=John&amp;lastname=De%20Doe&amp;dobYYYYMMDD=00010101&amp;address1=&amp;zipcode=&amp;phonenumber=447624222723&amp;city=&amp;country=</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">1.11</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>161203</value>
            </detail>
            <detail xsi:type="keyBooleanValuePair">
                <key>IsCustomerRegisteredAtProvider</key>
                <value>false</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>1898365</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>1ebd16a5-0baa-4027-9c01-175d3fba7cb8</paymentAccountID>
        </paymentAccount>
    </payment>
</initiatePaymentResponse>

The following parameters are returned in the response:

key (value type, account type, required)

value

IsCustomerDOBMatchedAtProvider (boolean)

Indicates the matching of the customer´s provider date of birth.

IsCustomerCountryMatchedAtProvider (boolean)

Indicates the matching of the customer´s country.

IsCustomerLastNameMatchedAtProvider (boolean)

Indicates the matching of the customer´s lastname.

IsCustomerRegisteredAtProvider (boolean)

Indicates if customer is registered at MuchBetter.

ProviderTransactionID (string)

Transaction ID in the MuchBetter system.

ProviderExternalID (string)

TransactionID used by the Kalixa payment service.

Notifications

The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification.

Example handlePaymentStateChangedNotification:

<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>KalixaAcceptDEMO</merchantID>
        <shopID>KalixaAcceptDEMO</shopID>
        <paymentMethod>
            <key>318</key>
            <value>MuchBetterDeposit</value>
        </paymentMethod>
        <merchantTransactionID>512-12755-n568-g32662-hgrghhh7</merchantTransactionID>
        <paymentID>7eeb6082-1c00-4827-bb0b-ffa2729f037b</paymentID>
        <userID>c3ba0665-68ef-4daf-a3e6-8e70a1</userID>
        <paymentProvider>
            <key>176</key>
            <value>MuchBetter</value>
        </paymentProvider>
        <amount currencyCode="EUR">14.00</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>7892d0d7-3fda-4a27-ba7b-1a4bed05d825</id>
            <definition>
                <key>29</key>
                <value>DepositedByProvider</value>
            </definition>
            <createdOn>2018-04-03T15:09:20.463</createdOn>
            <description />
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderReasonCode</key>
                    <value>COMPLETED</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">14.00</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>105387</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>999</value>
            </detail>
          <detail xsi:type="keyBooleanvaluePair">
                <key>IsCustomerRegisteredAtProvider</key>
                <value>true</value>
                    </detail>
                    <detail xsi:type="keyBooleanvaluePair">
                <key> IsCustomerLastNameMatchedAtProvider </key>
                <value>true</value>
           </detail>
          <detail xsi:type="keyBooleanvaluePair">
                <key>IsCustomerDOBMatchedAtProvider</key>
                <value>true</value>
                </detail>
                <detail xsi:type="keyBooleanvaluePair">
                <key>IsCustomerCountryMatchedAtProvider</key>
                <value>true</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>135e618f-f2d0-4e1b-a85a-4bf92f18819a</paymentAccountID>
            <details>
                <detail xsi:type="keyStringValuePair">
                    <key>accountNumber</key>
                    <value>447624222721</value>
                </detail>
            </details>
        </paymentAccount>
    </payment>
</handlePaymentStateChangedNotificationRequest>

State diagram:

Diagram below follows transaction states

594594