Credits and payouts with card details

Using the Backoffice API, you can send a credit payment POST request from server-to-server. You will need to enter the card details, payment, and billing details.

This page describes how to create a basic credit request and then how to create payout requests with the parameters required by the Card Schemes.

Basic credit with card details request

Here is an example of a test credit request with card details from a server-to-server environment.

Replace the {channelId} and the {auth_token} with your values.

curl https://eu-test.oppwa.com/v1/payments \
 -d "entityId={channelId}" \
 -d "amount=100.00" \
 -d "currency=EUR" \
 -d "paymentBrand=VISA" \
 -d "paymentType=CD" \
 -d "card.number=4200000000000000" \
 -d "card.holder=John Smith" \
 -d "card.expiryMonth=02" \
 -d "card.expiryYear=2027" \
 -d "card.cvv=123" \
 -d "merchantTransactionId=P175" \
 -d "testMode=EXTERNAL" \
 -H "Authorization: Bearer {auth_token}"

From the payment response, store the id of the successful request for future reference.

For a successful transaction, the response code is 200.

Basic credit with card details response

Here is an example response for a successful credit transaction in a SERVER-TO-SERVER environment.

{
  "id": "8ac7a4a192b3b5060192b471c0d82dfb",
  "paymentType": "CD",
  "paymentBrand": "VISA",
  "amount": "100.00",
  "currency": "EUR",
  "descriptor": "7548.8324.7369 ECOMChannel ",
  "merchantTransactionId": "P175",
  "result": {
    "code": "000.100.112",
    "description": "Request successfully processed in 'Merchant in Connector Test Mode'"
  },
  "resultDetails": {
    "ExtendedDescription": "Approved or completed successfully",
    "clearingInstituteName": "Postbank P.O.S. Transact GmbH",
    "ConnectorTxID1": "852105",
    "ConnectorTxID3": "26K00001",
    "AcquirerResponse": "00",
    "reconciliationId": "P175",
    "merchantAccountId": "8a8294184f1d2f31014f25d1b00609b9"
  },
  "card": {
    "bin": "420000",
    "last4Digits": "0042",
    "holder": "John Smith",
    "expiryMonth": "02",
    "expiryYear": "2027"
  },
  "risk": {
    "score": "0"
  },
  "buildNumber": "1a09c7f6b69eaea67758a3050d39aeeeeec97625@2024-10-21 15:02:36 +0000",
  "timestamp": "2024-10-22 13:36:46+0000",
  "ndc": "8ac7a4c890fc748b0190fe6ad56b0241_cf4d3a0aa0f342e3a5837f7af9b5d994",
  "source": "OPP",
  "paymentMethod": "CC",
  "shortId": "7548.8324.7369"
}

For full details of how to interpret a transaction response, see Transaction results.

For the gateway documentation of the Backoffice API, see Gateway Backoffice API documentation for Payout. Note that the credit request is described as a payout because the most common use case for this request is to make a standalone refund to a customer when a regular refund is not possible.

Basic credit with card details test request

You can test this request at Gateway Playground Credit Payment with the parameters as shown in the sample data here.

entityId={channelId}
amount=100.00
currency=EUR
paymentBrand=VISA
paymentType=CD
card.number=4200000000000000
card.holder=John Smith
card.expiryMonth=02
card.expiryYear=2027
card.cvv=123
merchantTransactionId=P175
testMode=EXTERNAL

Payout with card details requests

After you have created a basic credit request for testing, add the required parameters for payouts, with Visa Original Credit Transfers (OCT), MasterCard Payment of Winnings with MCC 7995, and MasterCard Send payouts. These parameters are for Trust Payments and PAYSTRAX.

Replace the {channelId} and the {auth_token} with your values.

Visa OCT payout

curl https://eu-test.oppwa.com/v1/payments \
 -d "entityId={channelId}" \
 -d "amount=100.00" \
 -d "currency=EUR" \
 -d "paymentBrand=VISA" \
 -d "paymentType=CD" \
 -d "merchant.city=Vancouver" \
 -d "recipient.givenName=Jane" \
 -d "recipient.surname=Smith" \
 -d "recipient.state=QC" \
 -d "recipient.country=CAN" \
 -d "recipient.accountNumberType=RTN_AND_BANK_ACCOUNT" \
 -d "recipient.accountNumber=1234567890" \
 -d "customParameters[CreditSenderName]=John Smith" \
 -d "customParameters[CreditSenderAddress]=Grillparzerstr 18|Munich|BAV|DEU|81675" \
 -d "customParameters[CreditSenderCity]=Munich" \
 -d "customParameters[CreditSenderState]=BAV" \
 -d "customParameters[CreditSenderCountry]=DEU" \
 -d "card.number=4200000000000000" \
 -d "card.holder=John Smith" \
 -d "card.expiryMonth=02" \
 -d "card.expiryYear=2027" \
 -d "card.cvv=123" \
 -d "merchantTransactionId=P175" \
 -d "testMode=EXTERNAL" \
 -H "Authorization: Bearer {auth_token}"

From the payment response, store the id of the successful request for future reference.

MasterCard Payment of winnings by MCC 7995 merchant

curl https://eu-test.oppwa.com/v1/payments \
 -d "entityId={channelId}" \
 -d "amount=100.00" \
 -d "currency=EUR" \
 -d "paymentBrand=MASTER" \
 -d "paymentType=CD" \
 -d "customer.givenName=John" \
 -d "customer.surname=Smith" \
 -d "customer.phone=0123456789" \
 -d "merchant.city=Vancouver" \
 -d "recipient.givenName=Jane" \
 -d "recipient.surname=Smith" \
 -d "recipient.accountNumberType=RTN_AND_BANK_ACCOUNT" \
 -d "recipient.accountNumber=1234567890" \
 -d "customParameters[TransactionTypeIdentifier]=C55" \
 -d "customParameters[DateOfFunds]=250901" \
 -d "customParameters[AdditionalTrace]=ABC123" \
 -d "customParameters[CreditSenderName]=John Smith" \
 -d "customParameters[CreditSenderAddress]=Grillparzerstr 18|Munich|BAV|DEU|81675" \
 -d "customParameters[CreditSenderCity]=Munich" \
 -d "customParameters[CreditSenderState]=BAV" \
 -d "customParameters[CreditSenderCountry]=DEU" \
 -d "card.number=4200000000000000" \
 -d "card.holder=John Smith" \
 -d "card.expiryMonth=02" \
 -d "card.expiryYear=2027" \
 -d "card.cvv=123" \
 -d "merchantTransactionId=P175" \
 -d "testMode=EXTERNAL" \
 -H "Authorization: Bearer {auth_token}"

MasterCard Send payout

curl https://eu-test.oppwa.com/v1/payments \
 -d "entityId={channelId}" \
 -d "amount=100.00" \
 -d "currency=EUR" \
 -d "paymentBrand=MASTER" \
 -d "paymentType=CD" \
 -d "merchant.city=Vancouver" \
 -d "recipient.givenName=Jane" \
 -d "recipient.surname=Smith" \
 -d "recipient.state=QC" \
 -d "recipient.country=CAN" \
 -d "recipient.accountNumberType=RTN_AND_BANK_ACCOUNT" \
 -d "recipient.accountNumber=1234567890" \
 -d "recipient.birthDate=1985-01-01" \
 -d "recipient.phone=0123456789" \
 -d "customParameters[TransactionTypeIdentifier]=C55" \
 -d "customParameters[DateOfFunds]=250901" \
 -d "customParameters[AdditionalTrace]=ABC123" \
 -d "customParameters[CreditSenderName]=John Smith" \
 -d "customParameters[CreditSenderAddress]=Grillparzerstr 18|Munich|BAV|DEU|81675" \
 -d "customParameters[CreditSenderCity]=Munich" \
 -d "customParameters[CreditSenderState]=BAV" \
 -d "customParameters[CreditSenderCountry]=DEU" \
 -d "card.number=4200000000000000" \
 -d "card.holder=John Smith" \
 -d "card.expiryMonth=02" \
 -d "card.expiryYear=2027" \
 -d "card.cvv=123" \
 -d "merchantTransactionId=P175" \
 -d "testMode=EXTERNAL" \
 -H "Authorization: Bearer {auth_token}"

For a successful transaction, the response code is 200.

Payout request parameters table

The following table provides more details about the above parameters.

Key	Example Value	Value Format / Options	Mandatory
entityId	{channelId}	AN32	Yes
amount	100.00	N10.N2	Yes
currency	EUR	A3	Yes
merchantTransactionId	ABC123	AN..255	No, but recommended
paymentBrand	MASTER	VISA, MASTER, and so on, as in Gateway documentation	Yes
paymentType	CD	CD	Yes
customer.givenName	John	AN..50	Mandatory for: Mastercard Payment of Winnings - MCC 7995.
customer.surname	Smith	AN..50	Mandatory for: Mastercard Payment of Winnings - MCC 7995.
customer.phone customer.mobile	0123456789	AN..25	Mandatory for: Mastercard Payment of Winnings - MCC 7995.
merchant.city	Vancouver	ANS13	Yes
recipient.givenName	Jane	AN48	Yes
recipient.surname	Smith	AN48	Yes
recipient.state	QC	ANS..3	Mandatory for: Visa OCTs and Mastercard Send to US and Canada
recipient.country	CAN	A3	Mandatory for: Visa OCTs and Mastercard Send to US and Canada
recipient. accountNumberType	RTN_AND_BANK_ACCOUNT	Indicates type of recipient's account. Possible values are: OTHER RTN_AND_BANK_ACCOUNT IBAN EMAIL PHONE_NUMBER BAN_AND_BIC WALLET_ID SOCIAL_NETWORK_ID	Yes
recipient.accountNumber	1234567890	ANS..50	Yes
customParameters[ TransactionTypeIdentifier]	C04	Possible values are: C04 - Gaming Replay C07 - Moneysend General Person to Person Transfer C52 - Moneysend General Transfer to Own Account C53 - Moneysend Agent Cash Out C54 - Moneysend Payment of Own Credit Card Bill C55 - Moneysend Business Disbursement C56 - Moneysend Govt. Non Profit Disbursement C57 - Rapid Merchant Settlement C65 - General Business to Business Transfer	Mandatory for: Mastercard Send Payment and Payment of Winnings transactions
customParameters[ DateOfFunds]	250901	YYMMDD	Mandatory for: Mastercard Send Payment and Payment of Winnings - MCC 7995
customParameters[ AdditionalTrace]	ABC123	N19 (should be unique per transaction)	Mandatory for: Mastercard Send Payment and Payment of Winnings - MCC 7995
customParameters[ CreditSenderName]	Jane Smith	AN..30	Yes
customParameters[ CreditSenderAddress]	Grillparzerstr 18\|Munich\|BAV\|DEU\|81675	AN.. 35 Street\|City\|StateCode(US Only)\|ISO3166 CountryCode\|PostalCode	Yes
customParameters[ CreditSenderCity]	Munich	AN..25	Yes
customParameters[ CreditSenderState]	BAV	AN3	Yes
customParameters[ CreditSenderCountry]	DEU	AN3	Yes