Amex
Authentication
In order to connect your Amex account with Leapfin, you need to request Amex to enable SFTP on your production account.
Afterwards, follow the instruction here to set up and a create a SFTP account. The following report is required by Leapfin:
- Global Reconciliation (GRRCN) report. Login to your Amex and download schema here
- You can also access the schema here
Leapfin needs following information regarding the SFTP account. Please contact Amex support for the information.
required fields:
- Server host name
- User name
- Password or Private key (either one of them will be sufficient)
optional fields:
- Private key password (required only if SFTP private key is password protected)
- Outbox or folder name (required only if the files are not placed in the root directory)
- Host key or Host key fingerprint (required only if you need enhanced security. Providing one of them will be sufficient)
- File decryption private key (required only if the files on SFTP server are encrypted)
- File decryption private key password (required only if the files on SFTP server are encrypted using a password protected key)
Data Sources
Once authenticated, Leapfin fetches information related to transactions, fees, discounts, plans and customers from Amex via SFTP.
Net Pay GRRCN File
Amex sends Global Reconciliation (GRRCN) reports, also known as Global Raw Data Reconciliation File, via sftp. GRRCN reports contains a daily file. Depend on the settlement account settings, there can be a monthly file as well. The contents of daily & monthly files also various based on settings.
The GRRCN report contains various types of records.
For each data row GRRCN file with header SUMMARY, it is imported as amex-summary
into Leapfin. For the schema of the SUMMARY, read page 28 here
Sample Data
{
"recordType":"SUMMARY",
"paymentDate":"20200103",
"payeeMerchantId":"6317xxxxxx",
"paymentCurrency":"USD",
"paymentNetAmount":"000000002219625",
"paymentTaxAmount":"000000000000000",
"bankAccountNumber":"xxx0000xx",
"bankIdentifierCode":"",
"paymentGrossAmount":"000000002378037",
"paymentDiscountAmount":"000000000076688",
"paymentAdjustmentAmount":"-000000000078039",
"paymentServiceFeeAmount":"000000000003685",
"payeeDirectDepositNumber":"0000000239",
"openingDebitBalanceAmount":"000000000000000",
"settlementAccountTypeCode":"",
"americanExpressPaymentNumber":"001Axxxx",
"uniquePaymentReferenceNumber":"",
"internationalBankAccountNumber":""
}
For each data row GRRCN file with header SUBMISSION, it is imported as amex-submission
into Leapfin. For the schema of the SUBMISSION record, read page 53 here
Sample Data
{
"filler": "",
"recordType": "SUBMISSION",
"trackingId": "",
"paymentDate": "20210113",
"transactions": [
{
"filler": "",
"sellerId": "",
"recordType": "TRANSACTN",
"terminalId": "",
"paymentDate": "20210113",
"approvalCode": "14xxxx",
"transactionId": "000xx274xxxxxx",
"payeeMerchantId": "xxx0099xx9",
"paymentCurrency": "USD",
"transactionDate": "20210106",
"transactionTime": "052428",
"serviceFeeAmount": "",
"installmentNumber": "",
"transactionAmount": "000000000000497",
"accelerationAmount": "",
"merchantLocationId": "",
"submissionCurrency": "JPY",
"transactionPricings": [
{
"filler": "",
"feeCode": "",
"sellerId": "",
"feeAmount": "000000000000000000000",
"recordType": "TXNPRICING",
"fillerBytes": "",
"discountRate": "000700",
"discountAmount": "000000000000003479000",
"payeeMerchantId": "xxx00xxx",
"paymentCurrency": "USD",
"paymentDateBytes": "20210113",
"transactionAmount": "000000000000497",
"merchantLocationId": "",
"submissionMerchantId": "xxx00xxx",
"transactionDateBytes": "20210106",
"invoiceReferenceNumber": "xxxx8524XIV",
"cardmemberAccountNumber": "XXXX182XXXXX1001",
"settlementAccountTypeCode": "002",
"americanExpressPaymentNumber": "xxx00xxx"
},
{
"filler": "",
"feeCode": "",
"sellerId": "",
"feeAmount": "000000000000000000000",
"recordType": "TXNPRICING",
"fillerBytes": "",
"discountRate": "004000",
"discountAmount": "000000000000019880000",
"payeeMerchantId": "xxx00xxx",
"paymentCurrency": "USD",
"paymentDateBytes": "20210113",
"transactionAmount": "xxx00xxx",
"merchantLocationId": "",
"submissionMerchantId": "xxx00xxx",
"transactionDateBytes": "20210106",
"invoiceReferenceNumber": "XXXXXX4MIV",
"cardmemberAccountNumber": "XXXX2XXXXX1001",
"settlementAccountTypeCode": "002",
"americanExpressPaymentNumber": "xxx00xxx"
}
],
"merchantCategoryCode": "5968",
"numberOfInstallments": "",
"submissionMerchantId": "xxx00xxx",
"businessSubmissionDate": "20210106",
"firstInstallmentAmount": "",
"invoiceReferenceNumber": "871XXXXIV",
"nonswipedIndicatorByte": "",
"acquirerReferenceNumber": "xxx00xxx",
"cardmemberAccountNumber": "xxx00xxx",
"submissionInvoiceNumber": "000000000000XX9",
"cardmemberReferenceNumber": "",
"settlementAccountTypeCode": "002",
"subsequentInstallmentAmount": "",
"americanExpressPaymentNumber": "xxx00xxx",
"transactionRejectedIndicator": "",
"americanExpressProcessingDate": "20210106",
"industrySpecificReferenceNumber": "",
"dataQualityNoncompliantErrorCode": "",
"dataQualityNoncompliantIndicator": "",
"submissionGrossAmountInPaymentCurrency": "000000000000966"
},
{
"filler": "",
"sellerId": "",
"recordType": "TRANSACTN",
"terminalId": "",
"paymentDate": "20210113",
"approvalCode": "410000",
"transactionId": "xxx00xxx",
"payeeMerchantId": "xxx00xxx",
"paymentCurrency": "USD",
"transactionDate": "20210106",
"transactionTime": "052428",
"serviceFeeAmount": "",
"installmentNumber": "",
"transactionAmount": "000000000000497",
"accelerationAmount": "",
"merchantLocationId": "",
"submissionCurrency": "JPY",
"transactionPricings": [
{
"filler": "",
"feeCode": "",
"sellerId": "",
"feeAmount": "000000000000000000000",
"recordType": "TXNPRICING",
"fillerBytes": "",
"discountRate": "000700",
"discountAmount": "000000000000003479000",
"payeeMerchantId": "xxx00xxx",
"paymentCurrency": "USD",
"paymentDateBytes": "20210113",
"transactionAmount": "xxx00xxx",
"merchantLocationId": "",
"submissionMerchantId": "xxx00xxx",
"transactionDateBytes": "20210106",
"invoiceReferenceNumber": "xxx00xxx",
"cardmemberAccountNumber": "xxx00xxx",
"settlementAccountTypeCode": "002",
"americanExpressPaymentNumber": "xxx00xxx"
},
{
"filler": "",
"feeCode": "",
"sellerId": "",
"feeAmount": "000000000000000000000",
"recordType": "TXNPRICING",
"fillerBytes": "",
"discountRate": "004000",
"discountAmount": "000000000000019880000",
"payeeMerchantId": "xxx00xxx",
"paymentCurrency": "USD",
"paymentDateBytes": "20210113",
"transactionAmount": "000000000000497",
"merchantLocationId": "",
"submissionMerchantId": "xxx00xxx",
"transactionDateBytes": "20210106",
"invoiceReferenceNumber": "xxx00xxx",
"cardmemberAccountNumber": "xxx00xxx",
"settlementAccountTypeCode": "002",
"americanExpressPaymentNumber": "xxx00xxx"
}
],
"merchantCategoryCode": "5968",
"numberOfInstallments": "",
"submissionMerchantId": "xxx00xxx",
"businessSubmissionDate": "20210106",
"firstInstallmentAmount": "",
"invoiceReferenceNumber": "xxx00xxx",
"nonswipedIndicatorByte": "",
"acquirerReferenceNumber": "xxx00xxx",
"cardmemberAccountNumber": "xxx00xxx",
"submissionInvoiceNumber": "xxx00xxx",
"cardmemberReferenceNumber": "",
"settlementAccountTypeCode": "002",
"subsequentInstallmentAmount": "",
"americanExpressPaymentNumber": "xxx00xxx",
"transactionRejectedIndicator": "",
"americanExpressProcessingDate": "20210106",
"industrySpecificReferenceNumber": "",
"dataQualityNoncompliantErrorCode": "",
"dataQualityNoncompliantIndicator": "",
"submissionGrossAmountInPaymentCurrency": "000000000000966"
}
],
"payeeMerchantId": "xxx00xxx",
"paymentCurrency": "USD",
"accelerationDate": "",
"transactionCount": "0000002",
"installmentNumber": "",
"submissionTaxRate": "",
"accelerationNumber": "",
"submissionCurrency": "JPY",
"submissionNetAmount": "000000000000920",
"submissionTaxAmount": "000000000000000",
"submissionMerchantId": "xxx00xxx",
"numberOfDaysInAdvance": "",
"businessSubmissionDate": "20210106",
"originalSettlementDate": "",
"submissionDiscountRate": "",
"submissionExchangeRate": "",
"submissionInvoiceNumber": "000000000000789",
"submissionDiscountAmount": "000000000000039",
"settlementAccountTypeCode": "002",
"submissionDebitGrossAmount": "000000000000966",
"submissionServiceFeeAmount": "000000000000007",
"submissionCreditGrossAmount": "000000000000000",
"americanExpressPaymentNumber": "xxx00xxx",
"americanExpressProcessingDate": "20210106",
"submissionAccelerationFeeAmount": "",
"submissionAccelerationFeeNetAmount": "",
"submissionGrossAmountInPaymentCurrency": "xxx00xxx",
"submissionGrossAmountInSubmissionCurrency": "xxx00xxx"
}
For each data row GRRCN file with header CHARGEBACK, it is imported as amex-chargeback
into Leapfin. For the schema of the chargeback record, read page 73 here
{
"billCode":"",
"sellerId":"",
"batchCode":"",
"netAmount":"-000000000004656",
"taxAmount":"000000000000000",
"recordType":"CHARGEBACK",
"grossAmount":"-000000000004880",
"paymentDate":"20200716",
"discountRate":"",
"discountAmount":"-000000000000224",
"serviceFeeRate":"000000",
"payeeMerchantId":"xxx00xxx",
"paymentCurrency":"USD",
"chargebackNumber":"xxx00xxx",
"serviceFeeAmount":"000000000000000",
"merchantLocationId":"",
"submissionCurrency":"MXN",
"chargebackReasonCode":"CBK0400005",
"submissionMerchantId":"xxx00xxx",
"businessSubmissionDate":"20200709",
"invoiceReferenceNumber":"xxx00xxx",
"cardmemberAccountNumber":"xxx00xxx",
"submissionInvoiceNumber":"000000000000000",
"settlementAccountTypeCode":"002",
"chargebackReasonDescription":"DEBIT FOR NO REPLY TO ENQUIRY",
"americanExpressPaymentNumber":"xxx00xxx",
"americanExpressProcessingDate":"20200709",
"industrySpecificReferenceNumber":""
}
For each data row GRRCN file with header ADJUSTMENT, it is imported as amex-adjustment
into Leapfin. For the schema of the adjustment record, read page 89 here
{
"billCode": "",
"sellerId": "",
"batchCode": "",
"netAmount": "-000000000020000",
"taxAmount": "000000000000000",
"recordType": "ADJUSTMENT",
"grossAmount": "000000000000000",
"paymentDate": "20200806",
"discountRate": "",
"discountAmount": "000000000000000",
"serviceFeeRate": "000000",
"payeeMerchantId": "xxx00xxx",
"paymentCurrency": "USD",
"adjustmentNumber": "000000000080036",
"serviceFeeAmount": "000000000020000",
"merchantLocationId": "",
"submissionCurrency": "KRW",
"adjustmentReasonCode": "ADJ0800646",
"submissionMerchantId": "xxx00xxx",
"businessSubmissionDate": "20200731",
"invoiceReferenceNumber": "",
"cardmemberAccountNumber": "",
"submissionInvoiceNumber": "000000000000000",
"settlementAccountTypeCode": "002",
"adjustmentReasonDescription": "ANNUAL FEE FOR MULTI CURRENCY PROCESSING",
"americanExpressPaymentNumber": "",
"americanExpressProcessingDate": "20200801",
"industrySpecificReferenceNumber": ""
}
For each data row GRRCN file with header FEEREVENUE, it is imported as amex-fee
into Leapfin. For the schema of the fee record, read page 105 here
{
"billCode": "678",
"batchCode": "846",
"recordType": "FEEREVENUE",
"paymentDate": "20200428",
"assetBillingTax": "",
"payeeMerchantId": "xxx00xxx",
"paymentCurrency": "USD",
"assetBillingAmount": "",
"feeOrRevenueAmount": "-000000000000001",
"merchantLocationId": "",
"payInGrossIndicator": "0",
"submissionMerchantId": "xxx00xxx",
"assetBillingDescription": "",
"feeOrRevenueDescription": "NONCOMPLIANCE FEE(S) TOTAL CNT 1 AMOUNT Z 1.00",
"americanExpressPaymentNumber": "xxx00xxx"
}
Mapping Logics
amex-submission
For each data row GRRCN file with header SUBMISSION, it is imported as amex-submission
into Leapfin. For the schema of the SUBMISSION record, read page 53 here
ID Format
For records created under amex-submission, the id format is
amex-submission.submissionInvoiceNumber
-amex-submission.americanExpressPaymentNumber
+ (if available) "-smallest ofamex-submission.transactions[].trasnactionPricings[].invoiceReferenceNumber
e.g. "000000000000781-9200871437-69078524MIV"
Create a payment
Leapfin creates a payment object for each transaction in amex-submission.transactions[]
Target: leapfinPayment (schema) | Source:amex-submission (schema) |
---|---|
objectType | “payment” |
id | amex-submission.transaction.transactionId |
amount | amex-submission.transaction.transactionAmount |
currencyCode | amex-submission.transaction.submissionCurrency |
date | amex-submission.transaction.transactionDate |
succeededDate | if amex-submission.transaction.transactionRejectedIndicator is "REJ", then set succeededDate as None.Otherwise, set succeededDate as amex-submission.transaction.transactionDate |
description | |
status | “succeeded” |
exchangeRate | we map in rate fromamex-submission.submissionGrossAmountInPaymentCurrency / amex-submission.submissionGrossAmountInSubmissionCurrency and currencyCode from amex-submission.paymentCurrency |
customFields | The following fields from source record are added: -- amount x exchangeRates.rate -- amex-submission.transaction.paymentCurrency -- amex-submission.transaction.invoiceReferenceNumber -- amex-submission.transaction.acquirerReferenceNumber -- amex-submission.transaction.submissionInvoiceNumber -- amex-submission.transaction.americanExpressPaymentNumber |
links | Add a link from the payout record to this record with: -- objectType = "payout" -- id = amex-submission.leapfinSummaryId |
Create a fee
Leapfin creates a fee object for each txnPricing
in amex-submission.transactions[transaction.transactionPricings[]]
if txnPricing.feeAmount
is greater than 0.
Target: LeapfinFee (schema) | Source:amex-submission (schema) |
---|---|
objectType | "fee" |
id | concatenate [amex-submission.transaction.transactionId , index , "fee"] with "-"- index is the numeric index of txnPricing within transaction.transactionPricings []. (index start from 0) |
amount | amex-submission.transaction.transactionPricings.txnPricing.feeAmount xexchangeRates.rate |
currencyCode | amex-submission.transaction.paymentCurrency |
date | amex-submission.transaction.txnPricing.transactionDateBytes |
description | service fee |
exchangeRates | we map in rate fromamex-submission.submissionGrossAmountInSubmissionCurrency / amex-submission.submissionGrossAmountInPaymentCurrency and currencyCode from amex-submission.SubmissionCurrency |
customFields | The following fields from source record are added: -- amex-submission.transaction.txnPricing.feeAmount -- amex-submission.transaction.submissionCurrency |
links | Add a link to the LineItem record with: -- objectType = "line-item" -- id = amex-submission.transaction.transactionId Add a link from the payout record to this record with: -- objectType = "payout" -- id = amex-submission.leapfinSummaryId |
Create a fee
Leapfin creates a fee object for each txnPricing
in amex-submission.transactions[transaction.transactionPricings[]]
if txnPricing.discountAmount
is greater than 0.
Target: LeapfinFee (schema) | Source:amex-submission (schema |
---|---|
objectType | "fee" |
id | concatenate [amex-submission.transaction.transactionId , index , "fee"] with "-"- index is the numeric index of txnPricing within transaction.transactionPricings []. (index start from 0) |
amount | amex-submission.transaction.transactionPricings.txnPricing.discountAmount xexchangeRates.rate |
currencyCode | amex-submission.transaction.paymentCurrency |
date | amex-submission.transaction.txnPricing.transactionDateBytes |
description | payment discount |
exchangeRates | we map in rate fromamex-submission.submissionGrossAmountInSubmissionCurrency / amex-submission.submissionGrossAmountInPaymentCurrency and currencyCode from amex-submission.SubmissionCurrency |
customFields | The following fields from source record are added: -- amex-submission.transaction.txnPricing.discountAmount -- amex-submission.transaction.submissionCurrency |
links | Add a link to the LineItem record with: -- objectType = "line-item" -- id = amex-submission.transaction.transactionId Add a link from the payout record to this record with: -- objectType = "payout" -- id = amex-submission.leapfinSummaryId |
amex-chargeback
For each data row GRRCN file with header CHARGEBACK, it is imported as amex-chargeback
into Leapfin. For the schema of the chargeback record, read page 73 here
ID Format
For records created under amex-chargeback, the id format is
amex-chargeback.chargebackNumber
-amex-chargeback.americanExpressPaymentNumber
e.g. "000000000023062-9227571304"
create a dispute
Leapfin creates a dispute object for from each amex-chargeback
record
Target: LeapfinDispute (schema) | Source: amex-chargeback (schema) |
---|---|
objectType | "dispute" |
id | amex-chargeback.Id |
amount | absolute value of amex-chargeback.transaction.grossAmount |
currencyCode | amex-chargeback.paymentCurrency |
date | amex-chargeback.businessSubmissionDate |
status | If amex-chargeback.grossAmount is less than 0, then set status as "lost".Otherwise, set status as "pending". |
initiatedDate | If status is "lost", set as amex-chargeback.americanExpressProcessingDate .Otherwise, set as null. |
resolvedDate | amex-chargeback.americanExpressProcessingDate |
description | None |
exchangeRates | None |
customFields | Following fields from source record are added: - amex-chargeback.submissionCurrency - amex-chargeback.chargebackNumber - amex-chargeback.invoiceReferenceNumber - amex-chargeback.submissionInvoiceNumber - amex-chargeback.americanExpressPaymentNumber |
links | Add a link from the payout record to this record with: -- objectType = "payout" -- id = amex-submission.leapfinSummaryId |
amex-fee
For each data row GRRCN file with header FEEREVENUE, it is imported as amex-fee
into Leapfin. For the schema of the fee record, read page 105 here
Create a fee
Leapfin creates a fee object from each amex-fee
record
Target: LeapfinFee (schema) | Source:amex-fee (schema) |
---|---|
objectType | "fee" |
id | amex-fee.Id |
amount | negative amex-fee.feeOrRevenueAmount |
currencyCode | amex-fee.paymentCurrency |
date | amex-fee.paymentDate |
description | amex-fee.feeOrRevenueDescription |
exchangeRates | None |
customFields | The following fields from source record are added: -- amex-fee.americanExpressPaymentNumber |
links | Add a link from the payout record to this record with: -- objectType = "payout" -- id = amex-submission.leapfinSummaryId |
amex-summary
For each data row GRRCN file with header SUMMARY, it is imported as amex-summary
into Leapfin. For the schema of the SUMMARY, read page 28 here
ID Format
For records created under amex-summary, the id format is
amex-summary.payeeMerchantId
-amex-summary.americanExpressPaymentNumber-data.paymentDate
e.g. "6317491066-001A8396-20200103"
Create a payout
Leapfin creates a payout object from each amex-summary
record
Target: LeapfinSettlement (schema) | Source:amex-summary (schema) |
---|---|
objectType | "payout" |
id | amex-summary.Id |
amount | amex-summary.paymentNetAmount |
currencyCode | amex-summary.paymentCurrency |
date | amex-summary.paymentDate |
status | "paid" |
description | None |
links | Add a link to the payment record with: -- objectType = "payment" -- id = Add a link to the fee record with: -- objectType = "fee" -- id =A Add a link to the dispute record with: -- objectType = "dispute" -- id = |
exchangeRates | None |
customFields | The following fields from source record are added: - amex-summary.paymentGrossAmount - amex-summary.paymentDiscountAmount - amex-summary.paymentServiceFeeAmount - amex-summary.paymentAdjustmentAmount - amex-summary.paymentTaxAmount - amex-summary.openingDebitBalanceAmount - amex-summary.uniquePaymentReferenceNumber - amex-summary.americanExpressPaymentNumber |
Create a fee
Leapfin creates a fee object from each time amex-summary.paymentServiceFeeAmount
is not 0
Target: LeapfinFee (schema) | Source:amex-summary (schema) |
---|---|
objectType | "fee" |
id | amex-summary.Id |
amount | amex-summary.paymentServiceFeeAmount |
currencyCode | amex-summary.paymentCurrency |
date | amex-summary.paymentDate |
description | service fee |
exchangeRates | None |
customFields | The following fields from source record are added: -- amex-summary.uniquePaymentReferenceNumber -- amex-summary.americanExpressPaymentNumber |
links | Add a link to the LineItem record with: -- objectType = "payout" -- id = amex-summary.Id Add a link from the payout record to this record with: -- objectType = "payout" -- id = `amex-submission.leapfinSummaryId |
Create a fee
Leapfin creates a fee object from each time amex-summary.paymentDiscountAmount
is not 0
Target: LeapfinFee (schema) | Source:amex-summary (schema) |
---|---|
objectType | "fee" |
id | amex-summary.Id |
amount | amex-summary.paymentDiscountAmount |
currencyCode | amex-summary.paymentCurrency |
date | amex-summary.paymentDate |
description | payment discount |
exchangeRates | None |
customFields | The following fields from source record are added: -- amex-summary.uniquePaymentReferenceNumber |
links | Add a link to the Payout record with: -- objectType = "payout" -- id = amex-summary.Id |
amex-adjustment
For each data row GRRCN file with header ADJUSTMENT, it is imported as amex-adjustment
into Leapfin. For the schema of the adjustment record, read page 89 here
ID Format
For records created under amex-adjustment, the id format is
amex-adjustmen.payeeMerchantId
-amex-adjustmen.adjustmentNumber
-amex-adjustmen.americanExpressPaymentNumber
e.g. "9450060231-000000000080036-9221670195"
Create a fee
Leapfin creates a fee object from each time amex-adjustment.serviceFeeAmount
is not 0
Target: LeapfinFee (schema) | Source:amex-adjustment (schema) |
---|---|
objectType | "fee" |
id | amex-adjustment.Id |
amount | amex-adjustment.serviceFeeAmount |
currencyCode | amex-adjustment.paymentCurrency |
date | amex-adjustment.businessSubmissionDate |
description | amex-adjustment.adjustmentReasonDescription |
exchangeRates | None |
customFields | Following fields from source record are added: - amex-adjustment.submissionCurrency - amex-adjustment.adjustmentNumber - amex-adjustment.invoiceReferenceNumber - amex-adjustment.americanExpressPaymentNumber |
links | Add a link to the Payout record with: -- objectType = "payout" -- id = amex-summary.Id |
Create a fee
Leapfin creates a fee object from each time amex-adjustment.discountAmount
is not 0
Target: LeapfinFee (schema) | Source: amex-adjustment (schema) |
---|---|
objectType | "fee" |
id | amex-adjustment.Id |
amount | amex-adjustment.discountAmount |
currencyCode | amex-adjustment.paymentCurrency |
date | amex-adjustment.businessSubmissionDate |
description | amex-adjustment.adjustmentReasonDescription |
exchangeRates | None |
customFields | Following fields from source record are added: - amex-adjustment.submissionCurrency - amex-adjustment.adjustmentNumber - amex-adjustment.invoiceReferenceNumber - amex-adjustment.americanExpressPaymentNumber |
links | Add a link to the Payout record with: -- objectType = "payout" -- id = amex-summary.Id |
Updated 7 months ago