In this topic:

Payment Retry Schedule

With a Retry Payment Schedule, you can set up the type of failed payments to be evaluated for the payment retry process, the maximum number of attempts and the frequency of retry attempts.

To create a new Retry Schedule:

Setting up Generic Reason Codes

With Generic Reason Codes, you can specify which failed payments are candidates for the retry process. To be evaluated for the retry process, the Payment Processor Reason code that is displayed on the payment failure needs to be mapped to the specified Generic Reason Codes from the Payment Retry Schedule.

Use the following endpoint to get a list of available generic reason codes:

GET http://example-dunning-api.gotransverse.com/dunning/2/generic-reasons

Response

[
{
  "code": "insufficient_funds",
  "name": "Insufficient Funds",
  "description": "Error codes associated to the account not having sufficient funds or reaching the max amount of charges or transactions"
},
{
  "code": "system_error_system_timeout",
  "name": "System Error or Timeout",
  "description": "Error codes associated to an issue with the system whether it is the issuer or the bank not responding in time or internal system error"
}
]

To add a new Generic Reason Code, use the following endpoint and sample payload.

POST http://example-dunning-api.gotransverse.com/dunning/2/generic-reasons

Request

{
  "code": "string",
  "name": "string",
  "description": "string"
}

Setting up Payment Processor with reason codes

To configure the Payment Processor for Payment Retry:

  1. Make sure the Payment Processor is associated with Dunning
  2. Add Payment Processor failure reason codes to the configuration

First, let’s check whether the Payment Processor that you are using is already associated with Dunning.

Retrieving Payment Processors on Dunning

GET http://example-dunning-api.gotransverse.com/dunning/2/processors

Response

[…
{
  "key": "cyber_source",
  "name": "Cybersource",
  "description": "Cybersource payment processor",
  "class_name": "com.transverse.bleep.domain.payment.processor.cybersource.CyberSourcePaymentProcessor"
}
…
]

In case the response body doesn’t contain the needed Payment Processor, add it using the following endpoint and request body.

Adding Payment Processor to Dunning

POST http://example-dunning-api.gotransverse.com/dunning/2/processors

Request

{
  "key": "braintree",
  "name": "Braintree",
  "description": "Braintree Payment Processor",
  "class_name": "com.transverse.bleep.domain.payment.processor.braintree.BraintreePaymentProcessor"
}

Response

{
  "key": "braintree",
  "name": "Braintree",
  "description": "Braintree Payment Processor",
  "class_name": "com.transverse.bleep.domain.payment.processor.braintree.BraintreePaymentProcessor"
}

Now, when your Payment Processor is added to Dunning, make sure it contains the needed payment processor failure reasons codes that later will be mapped on to the Generic Reason Codes.

Retrieve Payment Processor reason codes

GET http://example-dunning-api.gotransverse.com/dunning/2/processors/{processor-key}/reasons

If there are no needed payment processor reasons, add new ones using the following endpoint and request body.

Add Payment Processor reason code

POST http://example-dunning-api.gotransverse.com/dunning/2/processors/{processor-key}/reasons

Request

{
  "code": "207",
  "name": "Bank unavailable",
  "description": "Issuing Bank unavailable. Wait a few minutes and resend the request."
}

Response

{
  "code": "207",
  "name": "Bank unavailable",
  "description": " Issuing Bank unavailable. Wait a few minutes and resend the request."
}

Setting up failure reason code mappings

Failure reason code mappings provide a way to associate the payment failure reason codes to the Generic Reasons per the specified Payment Gateway. To make sure all needed failed payments are included into the Retry Series, retrieve the available mappings.Each Payment Gateway has a list of existing codes which are returned in case of error. For example, if the CyberSource Payment Gateway with the Credit Card payment method is set up, in case of error it returns one of the codes specified in the table here. With the Gotransverse Payment Retry mapping, you can associate error codes of your Payment Gateway with the Gotransverse generic reason codes.

Cyber Source example

Cyber Source Payment Gateway returns the 204 error code: Decline - Insufficient funds in the account. For this declined payment to be retried, you should map it on to the suitable Generic Reason Code that later will be associated with the Payment Retry Schedule. To do it, make sure this error code is not yet associated with any Generic Reason Code, and then create a new mapping if needed.

Retrieve available mappings

GET http://example-dunning-api.gotransverse.com/dunning/2/generic-reasons/insufficient_funds/processor-reasons

Response

[…  
{
  "code": "204",
  "name": "204",
  "description": "Insufficient funds in the account.",
  "processor_key": "cyber_source",
  "processor_name": "CyberSource"
},
…]

If there are no needed code mappings, you can upload them with the CSV file or using Dunning API. Here is how you can add a new mapping with API.

Create new failure reason mapping

POST http://example-dunning-api.gotransverse.com/dunning/2/generic-reasons/insufficient_funds/processor-reasons

Request

{
  "code": "210",
  "processor_key": "cyber_source"
}

Response

{
  "level": "INFO",
  "message": "Failure reason mapping was created successfully"
}

Creating a Payment Retry Schedule

Use the following endpoint and sample payload to create a new Payment Retry Schedule:

POST http://example-dunning-api.gotransverse.com/dunning/2/retry-schedules

Request

{
  "code": "123",
  "name": "sample retry schedule",
  "description": "additional information",
  "status": "DRAFT",
  "minimum_amount": 100,
  "max_retries": 5,
  "retry_interval_days": 2,
  "account_category_id": 770,
  "generic_reasons": [
   {
	"code": "insufficient_funds"
   }
]
}

Response

{
  "code": "123",
  "name": "sample retry schedule",
  "description": "additional information",
  "status": "DRAFT",
  "minimum_amount": 100,
  "max_retries": 5,
  "retry_interval_days": 2,
  "account_category_id": 770,
  "generic_reasons": [
      {
      "code": "insufficient_funds",
	  "name": "Insufficient Funds",
	  "description": "Error codes associated to the account not having sufficient funds or reaching the max amount of charges or transactions"
      }
]
}

Now, proceed with creating and running jobs for Payment Retry.

Top