Integrating a new PSP

PSP Integration

In order to integrate a new PSP, a new module named by the PSP name should be added to the backend project. Then the PSP name should be added to the PaymentServiceProvider enum.

enum class PaymentServiceProvider {
    BS_PAYONE,
    BRAINTREE,
    ADYEN
}

The main component in a PSP integration is the Psp interface. It contains all the necessary functions:

calculatePspConfig,
registerAlias,
preauthorize,
capture,
authorize,
reverse,
refund
deleteAlias.

The interface should be inherited from a new PSP module.

Calculate PSP config

This function is used to calculate the PSP configuration that will be returned to the Mobile SDK during the Alias creation. This configuration will contain important data to register an Alias like:

credit card check hash for BS Payone,
client token for Braintree,
payment session for Adyen.

During this call, a configuration for the PSP (BS Payone, Braintree, Adyen) will be sent and a configuration with the extra data will be returned to the mobile SDK.

Register Alias

If the backend is communicating with a PSP during the Alias creation, this call should be implemented. PspRegisterAliasRequestModel contains the following fields:

Parameter Name	Description	Type
aliasId	Stash! alias id	String
aliasExtra	The extra information for the wanted alias(CC, SEPA or PAY_PAL)	AliasExtra
pspConfig	PSP configuration	PspConfig

AliasExtra:

Parameter Name	Description	Type
ccConfig	Credit card configuration	CreditCardConfig
sepaConfig	SEPA configuration	SepaConfig
payPalConfig	PayPal configuration	PayPalConfig
personalData	Personal data	PersonalData
paymentMethod	CC, SEPA or PAY_PAL	String
payload	Adyen payload	String

CreditCardConfig:

Parameter Name	Description	Type
ccMask	Credit Card mask, e.g. VISA-1111	String
ccExpiry	Credit Card expiry date	String
ccType	Credit Card type	String
ccHolderName	Credit Card holder name	String

SepaConfig:

Parameter Name	Description	Type
iban	International bank account number	String
bic	Bank identifier code	String

PayPalConfig:

Parameter Name	Description	Type
nonce	PayPal nonce	String
billingAgreementId	Billing agreement id	String
deviceData	Device data collected by client	String

PersonalData:

Parameter Name	Description	Type
email	Customer's email	String
customerIp	Account holder's IP	String
firstName	Account holder's first name	String
lastName	Account holder's last name	String
street	Account holder's street	String
zip	Account holder's zip	String
city	Account holder's city	String
country	Account holder's country code	String
customerReference	Customer reference	String

PspConfig:

Parameter Name	Description	Type
merchantId	Merchant id	String
portalId	Portal identifier	String
key	Key	String
accountId	Account id	String
sandboxMerchantId	Sandbox (test) merchant id	String
sandboxPublicKey	Sandbox (test) public key	String
sandboxPrivateKey	Sandbox (test) private key	String
publicKey	Production (live) public key	String
privateKey	Production (live) private key	String
default	A flag whether is a default config or not
currency	Merchant's currency	String
country	Merchant's currency	String
locale	Merchant's locale	String
urlPrefix	Live URL prefix	String

PspRegisterAliasResponseModel will be returned. It contains the following fields:

Parameter Name	Description	Type
pspAlias	An alias returned by the PSP	String
billingAgreementId	The billing agreement id returned by PayPal	String
registrationReference	Customer reference	String

Preauthorize

This call is used for the preauthorization. It reserves the sent amount during a transaction. PspPaymentRequestModel contains the following fields:

Parameter Name	Description	Type
aliasId	Stash! alias id	String
aliasExtra	The extra information for the wanted alias(CC, SEPA or PAY_PAL)	AliasExtra
paymentData	Payment details	PaymentData
pspAlias	The alias returned by PSP	String
pspConfig	PSP configuration	PspConfig
purchaseId	The merchant's transaction id	String

PaymentData:

Parameter Name	Description	Type
amount	Amount in smallest currency unit (e.g. cent)	Int
currency	Currency	String
reason	Reason of the transaction	String

PspPaymentResponseModel will be returned, and it contains the following fields:

Parameter Name	Description	Type
pspTransactionId	The transaction id returned by PSP	String
status	SUCCESS or FAIL	String
customerId	The PSP customer id	String
error	If the PSP returned an error, it will be mapped to an internal error	String
errorMessage	The PSP error message	String

Capture

This call id used to charge the reserved amount during the preauthorization. The PspCaptureRequestModel contains the following fields:

Parameter Name	Description	Type
pspTransactionId	The preauthorized transaction id returned by PSP	String
amount	The amount that will be captured	Int
currency	Currency	String
pspConfig	PSP configuration	PspConfig
purchaseId	The merchant's transaction id	String

The PspPaymentResponseModel will be returned.

Authorize

This call is used for the "automatic" payment. It is the combination of the preauthorization and the capture. The request and response models are similar to the preauthorization ones.

Reverse

This call is used to cancel a transaction. It can be used only for the preauthorized transactions. The PspReversalRequestModel contains the following fields:

Parameter Name	Description	Type
pspTransactionId	The preauthorized transaction id returned by PSP	String
currency	Currency	String
pspConfig	PSP configuration	PspConfig
purchaseId	The merchant's transaction id	String

The PspPaymentResponseModel will be returned.

Refund

This call is used to refund a transaction. It can be used for the authorized and captured transactions, and it can be a partial refund. The PspRefundRequestModel contains the following fields:

Parameter Name	Description	Type
pspTransactionId	The authorized or captured transaction id returned by PSP	String
amount	The amount that will be captured	Int
currency	Currency	String
action	AUTH or CAPTURE	String
pspConfig	PSP configuration	PspConfig
purchaseId	The merchant's transaction id	String
paymentMethod	CC, SEPA or PAY_PAL	String