Save a customer and their card details. Once these are saved, they can be referenced for easier processing of transactions. In the Back Office UI, API shoppers are referred to as customers but they are the same resource.
Back Office UI
Create a Customer
- Click the Customers menu item.
- Click the New Customer button. The New Customer Profile window appears.
- Enter the Customer Name and Email Address.
- Enter the Company name, Phone Number, and any Additional Info, if required.
- If you are entering the Phone Number, select the appropriate Country Code from the dropdown list.
- To save the customer's shipping address, do the following:
- Toggle the Shipping Address button. Additional fields appear.
- Select the Country from the dropdown list.
- Enter the Address Line, Town/City, and Postal Code in the corresponding fields.
- Click the Create Profile button to save the customer details.
Add Card to a Customer
- Click the Customers menu item.
- Select the customer whose card details you want to add. The corresponding customer profile appears.
- In the Wallet section of the customer profile, click the Add Card button. The Add Payment Card window appears.
- Review and edit the Cardholder Name, if required.
- Enter the Card Number and the Expiry Date in MM/YY format.
- Enter the card's Security Code.
- To save the customer's billing address, do the following:
- Toggle the Billing Address button. Additional fields appear.
- Select the Country from the dropdown list.
- Enter the Address Line, Town/City, and Postal Code in the corresponding fields.
- Click the Add to Profile button to add the card details to the customer profile.
Create a Transaction
- See steps 1 to 7 under Create a Transaction in the One-off Payment page.
- In the Customer section, search for the customer profile by doing one of the following:
- In the Search for a customer field, enter a part of the customer's name and select the profile from the results.
- Select the customer profile from the Search for a customer dropdown list.
- In the Payment section, select the card to be used from the Payment Method dropdown list.
- Review the customer profile and card details that are populated in the fields and edit, if required.
- Click the Process Transaction button to proceed with the transaction. The transaction details will appear after the transaction is processed.
Create a Transaction from a Customer's Profile
- Click the Customers menu item.
- Select the customer you will create a transaction for. The corresponding customer profile appears.
- Click the Actions button, then select New Transaction. The New Transaction form appears with the customer's details automatically populated.
- See steps 4 to 6 under Create a Transaction in the One-off Payment page.
- Click the Process Transaction button to proceed with the transaction. The transaction details will appear after the transaction is processed.
Depending on your account settings, you may need to select a currency for the transaction amount. If your account is set to use only one currency, the default currency will be used.
API Integration
Converge API Resources: Shoppers, Stored Cards, Transactions
Create Shopper
- Send a Create Shopper POST request to the /shoppers endpoint.
- In your request, set the following parameters:
- fullName - The name of the customer. This is required.
- description - Any additional information about the customer.
- company - The customer's company name.
- primaryAddress - The customer's address that can be used for shipping and billing. It contains the fields below:
- street1 - The first address line.
- street2 - The second address line.
- city - The town or city.
- postalCode - The zip or postal code.
- countryCode - The ISO 3166-1 Alpha-3 country code.
- primaryPhone - The customer's phone number.
- email - The customer's email address.
- Wait for the response from the /shoppers endpoint. In the response, take note of the following:
- id - The shopper resource ID. This is used for retrieving and updating the shopper.
- href - The shopper resource URL. This is used for associating the shopper with a stored card.
Create Stored Card
- Send a Create StoredCard POST request to the /stored-cards endpoint.
- In your request, set the following parameters:
- shopper - The shopper resource URL. This is obtained from a successful Create Shopper response. This is required.
- card - The stored card details. It contains the fields below:
- holderName - The stored cardholder's full name.
- number - The stored card's personal account number. This value is not returned.
- expirationMonth - The stored card's expiration month. This is required.
- expirationYear - The stored card's expiration year. This is required.
- securityCode - The stored card's security code. This is required and the value is not returned.
- billTo - The stored card's billing address. It contains the fields below:
- street1 - The first address line.
- street2 - The second address line.
- city - The town or city.
- postalCode - The zip or postal code. This is required for UK merchants.
- countryCode - The ISO 3166-1 Alpha-3 country code.
- Wait for the response from the /stored-cards endpoint. In the response, take note of the following:
- id - The stored card resource ID. This is used for retrieving and updating the stored card.
- href - The stored card resource URL. This is used for associating the stored card with a shopper.
Create Transaction with a Stored Card
- Send a Create Transaction POST request to the /transactions endpoint.
- In your request, set the following parameters:
- type - The transaction type. The default value is "sale".
- total - The total amount of the transaction. It contains the fields below:
- amount - The actual value of the transaction. This is required.
- currencyCode - The ISO 4217 three-letter currency code. This is required.
- orderReference - The order reference number for the transaction.
- shopperInteraction - The type of interaction with the customer that generated this transaction. Valid values are the following: ecommerce (default), mailOrder, telephoneOrder, merchantInitiated. Note that using the default option will not authorize if the 3DS details are not provided.
- shopper - The shopper resource URL. This is obtained from a successful Create Shopper response.
- storedCard - The stored card resource URL. This is obtained from a successful Create StoredCard response.
- doCapture - The action to be used on the transaction. If set to true (default), the transaction will capture for settlement. If set to false, the transaction will authorize only.
- doSendReceipt - If set to true, receipt will be sent to the customer's email. If set to false (default), receipt will not be emailed.
- Wait for the response from the /transactions endpoint. In the response, take note of the following:
- id - The transaction resource ID. This is used for retrieving and updating the transaction.
- href - The transaction resource URL.
- isAuthorized - Indicates whether the transaction is authorized. Sale transactions are authorized by the gateway, processor, and issuer.
Examples
The following is an example of a JSON request for creating a shopper named John Doe.
POST "https://uat.api.converge.eu.elavonaws.com/shoppers"
{
"fullName": "John Doe",
"primaryAddress": {
"street1": "123 Baker St.",
"street2": "Suite B",
"city": "London",
"region": "England",
"postalCode": "NW1 6XE",
"countryCode": "GBR"
},
"primaryPhone": "+44 020 7946 0123",
"email": "john.doe@email.com"
}The following is an example of a successful JSON response to the request above.
{
"href": "https://uat.api.converge.eu.elavonaws.com/shoppers/pbrcccxy9pgk4qfdcbhf88w97hxv",
"id": "pbrcccxy9pgk4qfdcbhf88w97hxv",
"createdAt": "2022-04-04T19:32:38.566Z",
"modifiedAt": "2022-04-04T19:32:38.566Z",
"deletedAt": null,
"merchant": "https://uat.api.converge.eu.elavonaws.com/merchants/XrDXRBh9YHxwqQTj2Cmq7j49",
"defaultStoredCard": null,
"fullName": "John Doe",
"description": null,
"company": null,
"primaryAddress": {
"street1": "123 Baker St.",
"street2": "Suite B",
"city": "London",
"region": "England",
"postalCode": "NW1 6XE",
"countryCode": "GBR"
},
"primaryPhone": "+44 020 7946 0123",
"alternatePhone": null,
"fax": null,
"email": "john.doe@email.com",
"customReference": null,
"customFields": null
}The following is an example of a JSON request for creating a stored card under John Doe.
POST "https://uat.api.converge.eu.elavonaws.com/stored-cards"
{
"shopper": "https://uat.api.converge.eu.elavonaws.com/shoppers/pbrcccxy9pgk4qfdcbhf88w97hxv",
"card": {
"holderName": "John Doe",
"number": "5100.0800.0004.1251",
"expirationMonth": 1,
"expirationYear": 2025,
"securityCode": "123",
"billTo": {
"street1": "123 Baker St.",
"street2": "Suite B",
"city": "London",
"region": "England",
"postalCode": "NW1 6XE",
"countryCode": "GBR"
}
}
}The following is an example of a successful JSON response to the request above.
{
"href": "https://uat.api.converge.eu.elavonaws.com/stored-cards/g9fw9kg2fjfcdm62rb2f38cqmx9m",
"id": "g9fw9kg2fjfcdm62rb2f38cqmx9m",
"createdAt": "2022-04-04T19:39:26.578Z",
"modifiedAt": "2022-04-04T19:39:26.578Z",
"deletedAt": null,
"merchant": "https://uat.api.converge.eu.elavonaws.com/merchants/XrDXRBh9YHxwqQTj2Cmq7j49",
"shopper": "https://uat.api.converge.eu.elavonaws.com/shoppers/pbrcccxy9pgk4qfdcbhf88w97hxv",
"card": {
"holderName": "John Doe",
"panToken": {
"token": "9594435984992194335",
"provider": "ELAVON_C2_V1",
"type": "pan"
},
"panFingerprint": "brwmhqf8m7q49xc9wfg6t32hbhxm",
"expirationMonth": 1,
"expirationYear": 2025,
"billTo": {
"fullName": null,
"company": null,
"street1": "123 Baker St.",
"street2": "Suite B",
"city": "London",
"region": "England",
"postalCode": "NW1 6XE",
"countryCode": "GBR",
"primaryPhone": null,
"alternatePhone": null,
"fax": null,
"email": null
},
"maskedNumber": "XXXX.XXXX.XXXX.1251",
"last4": "1251",
"bin": "510008",
"scheme": "MasterCard",
"brand": "MasterCard Credit",
"fundingSource": "credit",
"issuingBank": "INTERNATIONAL CARD SERVICES BV",
"issuingCountry": "NLD",
"issuingCurrency": "EUR",
"isDebit": "false",
"isCorporate": "false",
"isDccAllowed": "true"
},
"verificationResults": {
"name": "unsupported",
"securityCode": "matched",
"addressStreet": "unsupported",
"addressPostalCode": "unsupported",
"threeDSecureV1": "unprovided",
"threeDSecureV2": "unprovided"
},
"customReference": null,
"customFields": null
}The following is an example of a JSON request for a EUR 20.00 payment using the stored card created under John Doe.
POST "https://uat.api.converge.eu.elavonaws.com/transactions"
{
"total": {
"amount": "20.00",
"currencyCode": "EUR"
},
"shopperInteraction": "telephoneOrder",
"storedCard": "https://uat.api.converge.eu.elavonaws.com/stored-cards/g9fw9kg2fjfcdm62rb2f38cqmx9m"
}The following is an example of a successful JSON response to the request above.
{
"href": "https://uat.api.converge.eu.elavonaws.com/transactions/hkptdq6b6w3bqvkv8fktc9d3fkck",
"id": "hkptdq6b6w3bqvkv8fktc9d3fkck",
"createdAt": "2022-04-04T19:48:57.574Z",
"modifiedAt": "2022-04-04T19:48:57.574Z",
"type": "sale",
"source": "directApiCall",
"merchant": "https://uat.api.converge.eu.elavonaws.com/merchants/XrDXRBh9YHxwqQTj2Cmq7j49",
"processorAccount": "https://uat.api.converge.eu.elavonaws.com/processor-accounts/KmvmfQJpCBJpXHyP2kgrK2hD",
"account": "https://uat.api.converge.eu.elavonaws.com/accounts/XrDXRBh9YHxwqQTj2Cmq7j49",
"total": {
"amount": "20.00",
"currencyCode": "EUR"
},
"totalRefunded": null,
"issuerTotal": null,
"conversionRate": null,
"markupRate": null,
"markupRateAnnotation": null,
"parentTransaction": null,
"description": null,
"shopperStatement": null,
"debtorAccount": null,
"customReference": null,
"shopperReference": null,
"processorReference": "I67NJF69JGL",
"issuerReference": "MSI042347",
"orderReference": null,
"shopperInteraction": "telephoneOrder",
"shopper": "https://uat.api.converge.eu.elavonaws.com/shoppers/pbrcccxy9pgk4qfdcbhf88w97hxv",
"shipTo": null,
"shopperEmailAddress": "john.doe@email.com",
"shopperIpAddress": null,
"shopperLanguageTag": null,
"shopperTimeZone": null,
"order": null,
"subscription": null,
"credentialOnFileType": "none",
"credentialOnFileData": null,
"card": {
"holderName": "John Doe",
"panToken": {
"token": "9594435984992194335",
"provider": "ELAVON_C2_V1",
"type": "pan"
},
"panFingerprint": "brwmhqf8m7q49xc9wfg6t32hbhxm",
"expirationMonth": 1,
"expirationYear": 2025,
"billTo": {
"fullName": null,
"company": null,
"street1": "123 Baker St.",
"street2": "Suite B",
"city": "London",
"region": "England",
"postalCode": "NW1 6XE",
"countryCode": "GBR",
"primaryPhone": null,
"alternatePhone": null,
"fax": null,
"email": null
},
"maskedNumber": "XXXX.XXXX.XXXX.1251",
"last4": "1251",
"bin": "510008",
"scheme": "MasterCard",
"brand": "MasterCard Credit",
"fundingSource": "credit",
"issuingBank": "INTERNATIONAL CARD SERVICES BV",
"issuingCountry": "NLD",
"issuingCurrency": "EUR",
"isDebit": "false",
"isCorporate": "false",
"isDccAllowed": "true"
},
"paymentLink": null,
"paymentSession": null,
"createdBy": null,
"modifiedBy": null,
"isHeldForReview": false,
"doCapture": true,
"doSendReceipt": true,
"isAuthorized": true,
"authorizationCode": "514858",
"verificationResults": {
"name": "unsupported",
"securityCode": "unprovided",
"addressStreet": "unsupported",
"addressPostalCode": "unsupported",
"threeDSecureV1": "unprovided",
"threeDSecureV2": "unprovided"
},
"state": "authorized",
"batch": null,
"customFields": null,
"relatedTransactions": [
],
"failures": [
],
"history": [
]
}For more request and response examples, and for the complete and detailed list of parameters, see the Shoppers resource, Stored Cards resource, and Transactions resource.