Upgrading from UPP 1.7/HPP to Paysafe Checkout
This page describes the benefits, migration approach, various scenarios, and responses/requests used to retrieve the data needed to successfully upgrade from UPP SOAP/HPP to Paysafe Checkout powered by the Payments API.
Benefits
By integrating Paysafe Checkout, you will have access to some of our latest payment methods such as Apple Pay, PayPal, Skrill, NETELLER, PaysafeCard, and PaysafeCash, along with other enhancements like network tokenization.
Migration approach
If you have a low number of PCI requirements (i.e. core card data is handled by Paysafe), you can onboard with Paysafe Checkout v2, powered by the Payments API.
To see how the Paysafe Checkout experience will work for your customers, visit our demo store.
To enable you to continue your re-billing cycle after migrating from UPP SOAP/HPP to the Payments API, we have enhanced the existing look up endpoint for UPP SOAP/HPP. When you look up a transaction made in UPP SOAP/HPP we will return a migration details object containing the necessary information for re-billing.
Onboarding with Checkout v2
For more information about Checkout v2, including details on how it works and the onboarding process, refer to the Checkout documentation.
Before integrating Paysafe's Checkout solution, it's necessary to understand some concepts that are important when processing payments with Checkout, such as payment handles and how sensitive customer information is saved and retrieved. For information about the concepts and capabilities of the Payments API, refer to the Payments API documentation.
You can retrieve your production API keys from Paysafe’s business portal Optic. You can log into Optic using your Netbanx Merchant Back Office credentials:
https://portals.paysafe.com/login
Note: If you don’t have Netbanx Merchant Back Office credentials, contact our support team.
To ensure that you are prepared for production, sign up for an Optic portal sandbox account to test Optic's functionality and explore new features within a dedicated test environment, without affecting your live systems.
UPP and Payments API enhancements
To improve your upgrade experience, we have made some enhancements to the UPP and Payments APIs.
Look up an authorization using the Netbanx reference
You can look up an authorization for a UPP transaction with the Payments API using the UPP authorization Netbanx reference.
Request endpoint:
POST https://api.test.paysafe.com/paymenthub/v1/payments/{netbanx_reference}
Look up a settlement using the Netbanx reference
You can look up a settlement for a UPP transaction with the Payments API using the UPP authorization Netbanx reference.
Request endpoint:
POST https://api.test.paysafe.com/paymenthub/v1/settlements/{netbanx_reference}
Process a refund using the Netbanx reference
You can process a refund for a UPP transaction with the Payments API using the UPP Netbanx reference.
Request endpoint:
POST https://api.test.paysafe.com/paymenthub/v1/settlements/{netbanx_reference}/refund
Process a recurring or top-up transaction
You can process subsequent recurring/top-up transactions with the Payments API for transaction sequences that were started using UPP by sending a GET request to the corresponding UPP API. You will receive data items in the response that you can use to process a subsequent merchant-initiated transaction (MIT) with the Payments API.
STEP 1: Send a GET request to the corresponding UPP API
If you have previously been processing subsequent recurring/ top-up transactions using UPP 2.0 (Hosted API/HPP), you must first send a GET request to the UPP 2.0 (Hosted API/HPP) endpoint.
Pass an additional parameter migration_details=true with the GET request.
Request endpoint:
GET https://pay.test.netbanx.com/hosted/v1/orders/{netbanx_reference}?migration_details=true
You can also pass an additional parameter profile_id with the request - this is the profile id of an existing customer.
- If the card does not exist in the specified profile, the card is saved and you will receive the standard response with a new token.
- If the card already exists in the profile, you will receive the token for the existing card in the response.
{
...
"transaction" : {
...
"migrationDetails" : {
"accountId" : "1002676890",
"initialTransaction" : {
"accountId" : "1002676890",
"id" : "1757629640",
"merchantRefNum" : "ee7dc1f4-e229-4cc1-9028-461cbba1f47c"
},
"profile" : {
"id" : "9ec4a04b-04b9-491e-a645-27b3adc3616c",
"paymentToken" : "C0OwClxx7kiDVi9"
}
},
...
}
}
If you have previously been processing subsequent recurring/ top-up transactions using the UPP SOAP API, you must first send a GET request to the UPP SOAP API.
The WSDL for the UPP SOAP API is available here: https://www.test.netbanx.com/netbanx/NetBanxAutostatement-v3.wsdl
Request endpoint:
https://www.test.netbanx.com/cgi-bin/soap_rpc
Pass an additional <addendum_data> item with <name> migration_details and <value> true with the request.
Request body:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:NetBanxAutostatement">
<soapenv:Header/>
<soapenv:Body>
<urn:get_transaction_details_by_reference>
<username>{username}</username>
<password>{password}</password>
<reference>{netbanx_reference}</reference>
<addendum_data>
<item>
<name>migration_details</name>
<value>true</value>
</item>
</addendum_data>
</urn:get_transaction_details_by_reference>
</soapenv:Body>
</soapenv:Envelope>
You can also pass an additional parameter profile_id with the addendum data - this is the profile id of an existing customer.
- If the card does not exist in the specified profile, the card is saved and you will receive the standard response with a new token.
- If the card already exists in the profile, you will receive the token for the existing card in the response.
A migration_details object is returned in the response.
Response:
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:nbx="urn:NetBanxAutostatement" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<nbx:get_transaction_details_by_referenceResponse>
<transaction xsi:type="nbx:transaction_details">
...
<migration_details xsi:type="nbx:migration_details">
<account_id xsi:type="xsd:string">1002676890</account_id>
<profile xsi:type="nbx:profile">
<id xsi:type="xsd:string">9ec4a04b-04b9-491e-a645-27b3adc3616c</id>
<payment_token xsi:type="xsd:string">C0OwClxx7kiDVi9</payment_token>
</profile>
<initial_transaction xsi:type="nbx:initial_transaction">
<id xsi:type="xsd:string">1757629640</id>
<account_id xsi:type="xsd:string">1002676890</account_id>
<merchant_reference>ee7dc1f4-e229-4cc1-9028-461cbba1f47c</merchant_reference>
</initial_transaction>
</migration_details>
</transaction>
</nbx:get_transaction_details_by_referenceResponse>
</soap:Body>
</soap:Envelope>
Using the migration details obtained from the request (HPP or SOAP), you can use the Payments API to process subsequent recurring or top-up transactions.
STEP 2: Authorize with the Payments API
For more information about payment requests, see Process Payment.
Request endpoint:
POST https://api.test.paysafe.com/paymenthub/v1/payments
In the body of the request, utilize the data obtained in the JSON migrationDetails or XML migration_details object as follows:
- Use the paymentToken property under profile object (SOAP: payment_token node under profile object) in the paymentHandleToken property.
- Use the id property under initialTransaction object (for SOAP: id node under initial_transaction object) in the initialTransactionId property under storedCredential object.
Request body:
{
"merchantRefNum": "502196ec-d548-4213-b7dd-221df666a55f",
"amount": 3500,
"currencyCode": "EUR",
"dupCheck": false,
"paymentHandleToken": "C0OwClxx7kiDVi9",
"description": "Magazine Subscription",
"storedCredential": {
"type": "RECURRING|TOPUP",
"occurrence": "SUBSEQUENT",
"initialTransactionId": "1757629640"
}
...
}
NOTE: If settleWithAuth is set to false, you need to settle the payment request - see Process Settlement.