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:

Customer enters their phone number on merchant site.
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

Customer initiates a payment via MuchBetter
Merchant send to PXP Financial initiatePaymentRequest with phone number which is registered on MuchBetter
PXP Financial sends initiatePaymentRequest to MuchBetter
PXP Financial receives initiatePaymentResponse
Merchant receives initiatePaymentResponse
Customer authorises transaction via MuchBetter mobile app
MuchBetter sends notification to PXP Financial
PXP Financial sends PaymentStateChangedNotification to Merchant

Customer doesn't have MuchBetter account

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

Sequence diagram

Following diagram describes MuchBetter deposit

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