Converge can automate your scheduled payments through the Plans and Subscriptions resources. For more information, see the Create Plan and Subscription page.
For integrator-managed wallets, the steps below outline the initial transaction for managing a series of scheduled payments with the same amount:
- Send a Create Transaction POST request to the /transactions endpoint.
- In your request, set the following parameters:
- 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.
- shopperInteraction - The type of interaction with the customer that generated this transaction. Valid values are the following: ecommerce (default), mailOrder, telephoneOrder. Note that using the default option will not authorize if the 3DS details are not provided.
- credentialOnFileType - Credential on file type. Set to "subscription".
- card - The customer's card details. It contains the fields below:
- holderName - The customer's full name.
- number - The cardholder's personal account number. This is required and the value is not returned.
- expirationMonth - The card's expiration month. This is required.
- expirationYear - The card's expiration year. This is required.
- securityCode - The card's security code. This is required and the value is not returned.
- billTo - The customer'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.
- total - The total amount of the transaction. It contains the fields below:
- 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.
- credentialOnFileData - The value returned from the initial use of a card in an integrator-managed wallet. This value must be saved and used in the succeeding transactions for the subscription.
The steps below outline the succeeding transactions for a series of scheduled payments with the same amount:
- Send a Create Transaction POST request to the /transactions endpoint.
- In your request, set the following parameters:
- 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.
- shopperInteraction - The type of interaction with the customer that generated this transaction. Set to "merchantInitiated".
- credentialOnFileType - Credential on file type. Set to "subscription".
- credentialOnFileData - The value returned from the initial use of a card in an integrator-managed wallet.
- card - The customer's card details. It contains the fields below:
- holderName - The customer's full name.
- number - The cardholder's personal account number. This is required and the value is not returned.
- expirationMonth - The card's expiration month. This is required.
- expirationYear - The card's expiration year. This is required.
- securityCode - The card's security code. This is required and the value is not returned.
- billTo - The customer'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.
- total - The total amount of the transaction. It contains the fields below:
- 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.
The following is an example of a JSON request for the initial transaction of a EUR 1.00 monthly subscription using John Doe's card.
POST "https://uat.api.converge.eu.elavonaws.com/transactions"
{
"total": {
"amount": "1.00",
"currencyCode": "EUR"
},
"shopperInteraction": "telephoneOrder",
"credentialOnFileType": "subscription",
"card": {
"holderName": "John Doe",
"number": "5100.0800.0004.1251",
"expirationMonth": 1,
"expirationYear": 2025
}
}The following is an example of a successful JSON response to the request above.
{
"href": "https://uat.api.converge.eu.elavonaws.com/transactions/yt2gg8t79fm3gjc9w3jvkfb83fwv",
"id": "yt2gg8t79fm3gjc9w3jvkfb83fwv",
"createdAt": "2023-04-12T18:10:42.404Z",
"modifiedAt": "2023-04-12T18:10:42.404Z",
"authorizationExpiresAt": "2023-04-19T18:10:42.404Z",
"type": "sale",
"paymentMethod": "Card",
"paymentMethodOrigin": "Card",
"source": "directApiCall",
"merchant": "https://uat.api.converge.eu.elavonaws.com/merchants/8dkkmt7yh4w4vdcwfk3mtg4qb9qt",
"processorAccount": "https://uat.api.converge.eu.elavonaws.com/processor-accounts/pxj468g3qfv4xvfy7br2vq27mbjf",
"account": "https://uat.api.converge.eu.elavonaws.com/accounts/8dkkmt7yh4w4vdcwfk3mtg4qb9qt",
"total": {
"amount": "1.00",
"currencyCode": "EUR"
},
"totalRefunded": null,
"issuerTotal": null,
"salesTax": null,
"conversionRate": null,
"markupRate": null,
"markupRateAnnotation": null,
"surchargeTotal": null,
"surchargeRate": null,
"parentTransaction": null,
"description": null,
"shopperStatement": null,
"debtorAccount": null,
"customReference": null,
"shopperReference": null,
"processorReference": "GUV5O0KVBDA",
"issuerReference": "MSI102181",
"orderReference": null,
"shopperInteraction": "telephoneOrder",
"shopper": null,
"shipTo": null,
"shopperEmailAddress": null,
"shopperIpAddress": null,
"shopperLanguageTag": null,
"shopperTimeZone": null,
"order": null,
"subscription": null,
"credentialOnFileType": "subscription",
"credentialOnFileData": "MMSI102181 0412 ",
"card": {
"holderName": "John Doe",
"panToken": {
"token": "9504330843000911384",
"provider": "ELAVON_C2_V1",
"type": "pan"
},
"paymentAccountReference": "M5100080107597654010759765401",
"panFingerprint": "ybgrr84w2xx6bmvvvkvh7t3v4gk2",
"expirationMonth": 1,
"expirationYear": 2025,
"billTo": 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,
"paymentGroup": null,
"paymentSession": null,
"createdBy": null,
"modifiedBy": null,
"customFields": null,
"isHeldForReview": false,
"doCapture": true,
"doSendReceipt": true,
"isAuthorized": true,
"authorizationCode": "511042",
"verificationResults": {
"name": "unsupported",
"securityCode": "unprovided",
"addressStreet": "unprovided",
"addressPostalCode": "unprovided",
"threeDSecureV1": "unprovided",
"threeDSecureV2": "unprovided",
"cryptogramSecurity": "unprovided"
},
"state": "authorized",
"batch": null,
"relatedTransactions": [
],
"failures": [
],
"history": [
]
}The following is an example of a JSON request for the succeeding transaction of a EUR 1.00 monthly subscription using John Doe's card.
POST "https://uat.api.converge.eu.elavonaws.com/transactions"
{
"total": {
"amount": "1.00",
"currencyCode": "EUR"
},
"shopperInteraction": "merchantInitiated",
"credentialOnFileType": "subscription",
"credentialOnFileData": "MMSI102181 0412 ",
"card": {
"holderName": "John Doe",
"number": "5100.0800.0004.1251",
"expirationMonth": 1,
"expirationYear": 2025
}
}The following is an example of a successful JSON response to the request above.
{
"href": "https://uat.api.converge.eu.elavonaws.com/transactions/j3fpfk7vrxtr8gkvtkppfwmjb9pv",
"id": "j3fpfk7vrxtr8gkvtkppfwmjb9pv",
"createdAt": "2023-04-12T18:19:19.462Z",
"modifiedAt": "2023-04-12T18:19:19.462Z",
"authorizationExpiresAt": "2023-04-19T18:19:19.462Z",
"type": "sale",
"paymentMethod": "Card",
"paymentMethodOrigin": "Card",
"source": "directApiCall",
"merchant": "https://uat.api.converge.eu.elavonaws.com/merchants/8dkkmt7yh4w4vdcwfk3mtg4qb9qt",
"processorAccount": "https://uat.api.converge.eu.elavonaws.com/processor-accounts/pxj468g3qfv4xvfy7br2vq27mbjf",
"account": "https://uat.api.converge.eu.elavonaws.com/accounts/8dkkmt7yh4w4vdcwfk3mtg4qb9qt",
"total": {
"amount": "1.00",
"currencyCode": "EUR"
},
"totalRefunded": null,
"issuerTotal": null,
"salesTax": null,
"conversionRate": null,
"markupRate": null,
"markupRateAnnotation": null,
"surchargeTotal": null,
"surchargeRate": null,
"parentTransaction": null,
"description": null,
"shopperStatement": null,
"debtorAccount": null,
"customReference": null,
"shopperReference": null,
"processorReference": "H1EU5698DUE",
"issuerReference": "MSI097306",
"orderReference": null,
"shopperInteraction": "merchantInitiated",
"shopper": null,
"shipTo": null,
"shopperEmailAddress": null,
"shopperIpAddress": null,
"shopperLanguageTag": null,
"shopperTimeZone": null,
"order": null,
"subscription": null,
"credentialOnFileType": "subscription",
"credentialOnFileData": null,
"card": {
"holderName": "John Doe",
"panToken": {
"token": "9589612975326107154",
"provider": "ELAVON_C2_V1",
"type": "pan"
},
"paymentAccountReference": "M5100080107597654010759765401",
"panFingerprint": "ybgrr84w2xx6bmvvvkvh7t3v4gk2",
"expirationMonth": 1,
"expirationYear": 2025,
"billTo": 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,
"paymentGroup": null,
"paymentSession": null,
"createdBy": null,
"modifiedBy": null,
"customFields": null,
"isHeldForReview": false,
"doCapture": true,
"doSendReceipt": true,
"isAuthorized": true,
"authorizationCode": "511920",
"verificationResults": {
"name": "unsupported",
"securityCode": "unprovided",
"addressStreet": "unprovided",
"addressPostalCode": "unprovided",
"threeDSecureV1": "unprovided",
"threeDSecureV2": "unprovided",
"cryptogramSecurity": "unprovided"
},
"state": "authorized",
"batch": null,
"relatedTransactions": [
],
"failures": [
],
"history": [
]
}