MIT batches via SFTP
This feature allows merchants to send FlexCharge batches of failed transactions for subscriptions without integration.
Step 1. Create a Sandbox account
If you don't already have a Sandbox account with the required credentials to start using our APIs, you can request one at [email protected]
Step 2. Get credentials for our SFTP
Share with us your public SSH key so that we can provide a secured access to our server, as well as the IP address from which the batches will be sent, so that we can whitelist it.
We'll then create 2 dedicated folders for you: one for inbound files, one for outbound files.
Step 3. Authenticate
Use your AppKey and AppSecret to retrieve a bearer token and authenticate your requests.
How to /authenticate.
Step 4. Sandbox environment
Inbound
/transmit
Send a copy of every successful transaction as an array of /transmit. We will use it to build a customized risk model based on your volumes.
For Sandbox, send us a sample file containing some transactions. We will process it as a certification test.
For Production, you will send us the copies of your transactions through a daily batch. Please note that copies of transactions must be sent within 24 hours maximum.
| Format | JSON or .csv |
| Header | Must contain your - mid, your FlexCharge Merchant Identification Number. Get your Mid ID- Authorization: bearer, token retrieved by /oauth2/token |
| Body | An array of /transmit. |
| Maximum size per file | 2000 rows. |
| PCI data | No PCI data is required for this file, no need for tokenization. |
/tokenize
You will first need to /tokenize the payment method, and then send us a sample file containing failed transactions as an array of /evaluate. We will process it as a certification test.
No real PCI data in Sandbox environment
Make sure you only use whitelisted credit cards for the Sandbox.
/evaluate
We will process it as a certification test.
| Format | JSON |
| Configuration | Must contain your - mid, your FlexCharge Merchant Identification Number. Get your Mid ID- authorizationToken: bearer, token retrieved by /oauth2/token- expiryDateUtc, period during which FlexCharge will retry the batch.(NB: a specific expiryDateUtc can be set for each transaction, the one in the header will be used as default) |
| Transaction requests | An array of /evaluate. |
| PCI data | Must be tokenized test data . Data cannot be hashed. |
File size
Maximum 2k requests per file. Send multiple files if necessary
Request example
{
"mid": "a8a0a74d-2509-4cbc-9eb5-879c7a34eb45",//merchant's mid can be found in the Sandbox account
"authorizationToken": "Bearer abc123def456", //replace with bearer returned by oauth2
"expiryDateUtc": "2023-04-05T01:23:45.678Z", //default expiry date and time for the whole batch
"requests": [
{
"isMIT": true,
"isRecurring": true,
"subscription": {
"subscriptionId": "sub_123456",
"schemeTransactionId": "txn_789012",
"schemeBrand": "Visa",
"interval": "Monthly",
"price": 2599,
"currency": "USD",
"paymentNumber": 2,
"totalPayments": 12
},
"threeDSecure": {
"threeDsVersion": "2.1.0",
"ecommerceIndicator": "02",
"authenticationValue": "abcdefg12345",
"directoryServerTransactionId": "ds_987654",
"xid": "xid_246810",
"authenticationValueAlgorithm": "SHA-256",
"directoryResponseStatus": "Y",
"authenticationResponseStatus": "Y",
"enrolled": "Y"
},
"transaction": {
"id": "3478613",
"timestampUtc": "0001-01-01T00:00:00Z",
"timezoneUtcOffset": 0,
"amount": 19975,
"currency": "USD",
"responseCode": "203",
"avsResultCode": "M",
"cvvResultCode": "NA",
"processorName": "Acme Payments",
"cavvResultCode": "2",
"responseCodeSource": "NMI",
"responseDescription": "Activity limit exceeded",
"responseStatus": "DECLINED",
"transactionType": "CAPTURE"
},
"payer": {
"id": "customer123",
"email": "[email protected]",
"phone": "+1 555-123-4567",
"birthdate": "1990-01-01"
},
"orderItems": [
{
"sku": "SKU123",
"name": "Subscription 1",
"description": "Description of Subscription 1",
"amount": 20000,
"discountAmount": 0,
"tax": 100,
"quantity": 1
},
{
"sku": "SKU456",
"name": "Subscription 2",
"description": "Description of Subscription 2",
"amount": 10000,
"discountAmount": 0,
"tax": 50,
"quantity": 1
}
],
"shippingInformation": {
"firstName": "John",
"lastName": "Doe",
"phone": "+1 555-123-4567",
"country": "United States",
"countryCode": "US",
"addressLine1": "123 Main St.",
"city": "CA",
"zipcode": "94111"
},
"merchant": {
"country": "US",
"mcc": 1234,
"id": "merchant123",
"name": "Acme Inc."
},
"paymentMethod": {
"holderName": "John Doe",
"cardType": "CREDIT",
"cardBrand": "VISA",
"cardCountry": "United States",
"cardIssuer": "Acme Bank",
"cardFingerprint": "abcd1234",
"expirationMonth": 2028,
"expirationYear": 12,
"cardBinNumber": "123456",
"cardLast4Digits": "7890",
"cardNumber": "zJb6YF7pL5gk8x9VhRnSwHd4q2t" //Do not send credit card number in clear, send token returned by /tokenize
},
"billingInformation": {
"firstName": "John",
"lastName": "Doe",
"phone": "+1 555-123-4567",
"country": "United States",
"countryCode": "US",
"addressLine1": "123 Main St.",
"state": "CA",
"city": "San Francisco",
"zipcode": "94111"
},
"mid": "a8a0a74d-2509-4cbc-9eb5-879c7a34eb45",
"orderId": "ed44736a-b5fa-4bc2-bfb9-0e873bc09511",
"idempotencyKey": "abcd1234",
"senseKey": "1234567890"
},
{
"isMIT": true,
"isRecurring": true,
"isDecline": true,
"subscription": {
"subscriptionId": "sub_654321",
"schemeTransactionId": "txn_210987",
"schemeBrand": "Mastercard",
"interval": "Weekly",
"price": 15.99,
"currency": "USD",
"paymentNumber": 3,
"totalPayments": 52
},
"threeDSecure": {
"threeDsVersion": "2.2.0",
"ecommerceIndicator": "01",
"authenticationValue": "hijklm67890",
"directoryServerTransactionId": "ds_456789",
"xid": "xid_135790",
"authenticationValueAlgorithm": "SHA-512",
"directoryResponseStatus": "A",
"authenticationResponseStatus": "C",
"enrolled": "Y"
},
"transaction": {
"id": "1234567",
"timestampUtc": "0001-01-01T00:00:00Z",
"timezoneUtcOffset": 0,
"amount": 14999,
"currency": "USD",
"responseCode": "204",
"avsResultCode": "N",
"cvvResultCode": "M",
"processorName": "XYZ Payments",
"cavvResultCode": "1",
"responseCodeSource": "Braintree",
"responseDescription": "Insufficient funds",
"responseStatus": "DECLINED",
"transactionType": "AUTHORIZE"
},
"payer": {
"id": "customer456",
"email": "[email protected]",
"phone": "+1 555-987-6543",
"birthdate": "1985-05-05"
},
"orderItems": [
{
"sku": "SKU789",
"name": "Product 3",
"description": "Description of Product 3",
"amount": 30000,
"discountAmount": 0,
"tax": 150,
"quantity": 2
},
{
"sku": "SKU012",
"name": "Product 4",
"description": "Description of Product 4",
"amount": 25000,
"discountAmount": 0,
"tax": 125,
"quantity": 1
}
],
"shippingInformation": {
"firstName": "Jane",
"lastName": "Doe",
"phone": "+1 555-987-6543",
"country": "United States",
"countryCode": "US",
"addressLine1": "456 Oak St.",
"city": "NY",
"zipcode": "10001"
},
"merchant": {
"country": "US",
"mcc": 5678,
"id": "merchant456",
"name": "XYZ Inc."
},
"paymentMethod": {
"holderName": "Jane Doe",
"cardType": "CREDIT",
"cardBrand": "MASTERCARD",
"cardCountry": "United States",
"cardIssuer": "XYZ Bank",
"cardFingerprint": "efgh5678",
"expirationMonth": 2028,
"expirationYear": 12,
"cardBinNumber": "123456",
"cardLast4Digits": "7890",
"cardNumber": "zJb6YF7pL5gk8x9VhRnSwHd4q2t" //Do not send credit card number in clear, send token returned by /tokenize
},
"billingInformation": {
"firstName": "Jane",
"lastName": "Doe",
"phone": "+1 555-987-6543",
"country": "United States",
"countryCode": "US",
"addressLine1": "456 Oak St.",
"city": "NY",
"zipcode": "10001"
},
"mid": "a8a0a74d-2509-4cbc-9eb5-879c7a34eb45",
"orderId": "ed44736a-b5fa-4bc2-bfb9-0e873bc09511",
"idempotencyKey": "abcd1234",
"senseKey": "1234567890"
}
]
}
Outbound: Submitted or Validation
Once we have received the /evaluate batch, we will respond with either one of these response files:
- Submitted: your batch was collected and will now be processed
- Validation error: your batch contains errors. Please correct them and resubmit.
Subscribe to a webhook
FlexCharge will retry every transaction in the batch for the period of time you have set withexpiryDateUtc.
Get notified as soon as the status of one transaction is updated. How to subscribe to a webhook.
Possible status update for each transaction: APPROVED (the order was successfully rescued by FLexCharge) or EXPIRED(FlexCharge couldn't rescue this transaction during this period of time)
Step 5. Production environment
Once we have validated that the entire flow runs as expected, we will then move to production environment.
Inbound
/transmit
Send a copy of every transaction as an array of /transmit. We will use it to build a customized risk model based on your volumes.
Send us the copies of your transactions through a daily batch. Please note that copies of transactions must be sent within 24 hours maximum
All transactions = Successful, failed, Initials and rebills.
| Format | JSON |
| Header | Must contain your - mid, your FlexCharge Merchant Identification Number. Get your Mid ID- Authorization: bearer, token retrieved by /oauth2/token |
| Body | An array of /transmit |
| Maximum size per file | 2000 rows. |
| PCI data | No PCI data is required for this file. |
tokenize
Before sending a a batch of failed transactions, you will first need to /tokenize each payment method.
/evaluate
| Format | JSON |
| Configuration | Must contain your - mid, your FlexCharge Merchant Identification Number. Get your Mid ID- authorizationToken: bearer, token retrieved by /oauth2/token- expiryDateUtc, period during which FlexCharge will retry the batch.(NB: a specific expiryDateUtc can be set for each transaction, the one in the header will be used as default) |
| Transaction requests | An array of /evaluate. |
| PCI data | Must be tokenized. Data cannot be hashed. |
File size
Maximum 2k requests per file. Send multiple files if necessary
Send only MIT that have just failed
The FlexCharge service is optimized to work with failed Merchant Initiated Transactions (MIT) that have just failed. These need to be passed to FlexCharge on that day (and not after a few days or weeks) and should not be retried by the Merchant up to the set expiry date.
Request example
{
"mid": "93af3a71-8505-49dc-85e2-9a5fce6a014a",
"authorizationToken": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI4YWMyMGJlZS0wZTI3LTRkZTEtOTIyYS1kMzg2ZDcyMDUxZmEiLCJ1bmlxdWVfbmFtZSI6IjhhYzIwYmVlLTBlMjctNGRlMS05MjJhLWQzODZkNzIwNTFmYSIsImp0aSI6IjBhZjI2NDNmLWQ3NTUtNDUzZC05NWZmLWZkYzcxZDg2N2U1ZSIsImlhdCI6IjE2ODA2MjE3MTYxOTQiLCJhdWQiOlsiYXBpLWNsaWVudC1zZXJ2aWNlIiwiZWxpZ2liaWxpdHktc2VydmljZSIsIm9yZGVycy1zZXJ2aWNlIl0sImN1c3RvbTptaWQiOiI5M2JmM2Y3MS04NTA1LTQ5ZGMtODVlMi05YTVmY2U2YTAxNGEiLCJuYmYiOjE2ODA2MjE3MTYsImV4cCI6MTY4MDYyMjMxNiwiaXNzIjoiQXBpLUNsaWVudC1TZXJ2aWNlIn0.p0icLxAIydvw2GDqNXcLiC-kwnsAEvLdnjZOW552onQ",
"expiryDateUtc": "2023-04-05T01:23:45.678Z",
"requests": [
{
"isDeclined": true,
"mid": "93af3a71-8505-49dc-85e2-9a5fce6a014a",
"orderId": "ORDER123",
"descriptor": "ACME INC",
"merchant": {
"name": "Merchant name",
"id": "93bf3f71-8505-49dc-85e2-9a5fce6a014a",
"mcc": "701",
"country": "USA"
},
"idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"transaction": {
"id": "1680621715284",
"timestampUtc": "0001-01-01T00:00:00",
"timezoneUtcOffset": 0,
"amount": "6420",
"currency": "USD",
"responseCode": "202",
"responseCodeSource": "nmi",
"avsResultCode": "M",
"cvvResultCode": "M",
"cavvResultCode": "2",
"cardNotPresent": false
},
"payer": {
"email": "[email protected]",
"phone": "5032219597"
},
"paymentMethod": {
"holderName": "JOHN DOE",
"cardType": "debit",
"cardBrand": "VISA",
"cardCountry": "US",
"expirationMonth": "10",
"expirationYear": "2033",
"cardNumber": "4HV330MHAAXb9V1Z2iZH5R6R9EC", /**This is the tokenized PCI data**/
"cardBinNumber": "54138900",
"cardLast4Digits": "0010"
},
"billingInformation": {
"firstName": "JOHN",
"lastName": "DOE",
"country": "US",
"countryCode": "US",
"addressLine1": "478 EAST ST",
"addressLine2": "",
"state": "PA",
"city": "BLOOMSBURG",
"zipcode": "178151847"
},
"shippingInformation": null,
"orderItems": [
{
"sku": "123",
"name": "Subscription 1",
"description": "Subscription 111",
"amount": "6420",
"quantity": 1
}
],
"isRecurring": true,
"subscription": {
"subscriptionId": "SUBSCRIPTION123",
"interval": "monthly",
"price": "6420",
"currency": "USD"
},
"expiryDateUtc": "2021-09-30T00:00:00",
"additionalFields" : null
}
]
}
Secured Processing
We will securely process the transaction file, by validating its format, running security checks, and then decrypting it.
Outbound: Submitted or Validation
Once we have received the /evaluate batch, we will respond with either one of these response files:
- Submitted: your batch was collected and will now be processed
- Validation error: your batch contains errors. Please correct them and resubmit.
Processing times
SFTP processing is async: once you have uploaded your files, they won't appear immediately on your portal.
The system processes transactions twice a day:
- 1pm and 6pm UTC
Result will be known on:
- the next day at 12pm UTC
Subscribe to a webhook
FlexCharge will retry every transaction in the batch for the period of time you have set withexpiryDateUtc.
Get notified as soon as the status of one transaction is updated. How to subscribe to a webhook.
Possible status update for each transaction: APPROVED (the order was successfully rescued by FlexCharge) or EXPIRED(FlexCharge couldn't rescue this transaction during this period of time)
Updated 4 months ago