Upgrading from UPP SOAP to the Payments API
This page describes the benefits, migration approach, various scenarios, and responses/requests used to retrieve the data needed to successfully upgrade from UPP SOAP to the Payments API.
Benefits
By integrating Paysafe's Payments API, you will have access to our latest payment methods such as Apple Pay, Google Pay, PayPal, Skrill, NETELLER, PaysafeCard, and PaysafeCash, along with other enhancements like network tokenization.
Migration approach
If you have a high number of PCI requirements (i.e. you are responsible for handling card data) and are utilizing a server-to-server connection with SOAP XML, you can onboard with the Payments API.
To enable you to continue your re-billing cycle after migrating from UPP XML to the Payments API, we have enhanced the existing LookUp endpoint for UPP XML. When you look up a transaction made in UPP XML we will return a migration details object containing the necessary information for re-billing.
Onboarding with the Payments API
Before integrating Paysafe's Payments API solution, it's important to understand concepts 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 several enhancements to the UPP and Payments APIs.
Look up an authorization using the Netbanx reference
You can look up an authorization for a UPP XML 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 XML 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 XML 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 XML by first sending a GET request to the UPP XML 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 UPP XML API
If you have previously been processing subsequent recurring/top-up transactions using the UPP XML API, you must first send a GET request to the UPP XML API.
The WSDL for the UPP XML 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>
You can now process subsequent recurring or top-up transactions with the Payments API using the migration details obtained from the request.
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 XML migration_details object as follows:
- Use the paymentToken property under profile object (XML: 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.