Integration Setup

Marqeta setup

For help with setting up the production environment, please contact Marqeta.

Mambu setup

Create Mambu user

Log in to your Mambu environment, create a user with API access for MPO and grant necessary permissions or a role. Copy the username and password.

Create a current account

Create a Current Account product and enable the Allow Technical Overdrafts option for it.

Create transaction channels

Create the following transaction channels in Mambu. You can use the naming suggested below or you can choose your own naming convention for Transaction Channels.

• Marqeta.authorization.clearing.{currency}
• Marqeta.authorization.clearing.atm.withdrawal.{currency}
• Marqeta.refund.{currency}
• Marqeta.original.credit.authorization.{currency}
• Marqeta.refund.authorization.clearing.{currency}
• Marqeta.authorization.clearing.quasi.cash.{currency}
• Marqeta.authorization.clearing.cashback.{currency}
• Marqeta.pindebit.{currency}
• Marqeta.pindebit.cashback.{currency}
• Marqeta.pindebit.ATM.Withdrawal.{currency}
• Marqeta.pindebit.authorization.clearing.{currency}
• Marqeta.pindebit.reversal.{currency}
• Marqeta.authorization.clearing.representment.{currency}
• Marqeta.original.credit.auth.plus.capture.{currency}
• Marqeta.authorization.clearing.chargeback.{currency}
• Marqeta.authorization.clearing.chargeback.completed.{currency}
• Marqeta.pindebit.chargeback.{currency}
• Marqeta.pindebit.chargeback.completed.{currency}
• Marqeta.account.funding.authorization.clearing.{currency}
• Marqeta.pindebit.refund.reversal.{currency}
• Marqeta.original.credit.auth_plus_capture.reversal.{currency}
• Marqeta.authorization.clearing.chargeback.reversal.{currency}
• Marqeta.pindebit.chargeback.reversal.{currency}

Each transaction channel should have its own linked general ledger (GL) account. Refer to the creating your chart of accounts article in our User Guide for more information on this process. The GL account type must be Asset, as it will overwrite the Transaction Source GL configured at the deposit product level.

Transaction Channels can be configured for multiple currencies. The .{currency} suffix appended to the transaction channel ID allows the connector to handle card transactions in multiple currencies.

Example

Organization allows posting card transactions in two different currencies: EUR and GBP. Two sets of Transaction channels should be created as follows:

Transaction channels for EUR

Transaction Channels for GBP

In the connector setup, the transaction channels should be saved without the .{currency} suffix. This suffix is dynamically added to the transaction channel ID by the connector, based on the currency received in the payload. This means that even if you have, for example, four transactions in Mambu to represent four different currencies, there will only be one matching transaction channel in the connector itself.

 "transactionChannels": {
            "authorizationClearingAtmWithdrawalChannel": "auth.clearing.atm.withdrawal",
            "refundChannel": "refund",
            "authorizationClearingChannel": "auth.clearing",
            "originalCreditAuthorizationChannel": "original.credit.auth",
            "refundAuthorizationClearingChannel": "refund.auth.clearing",
            "authorizationClearingQuasiCashChannel": "auth.clearing.quasi.cash",
            "authorizationClearingCashbackChannel": "auth.clearing.cashback",
            "pindebitChannel": "pindebit",
            "pindebitAtmWithdrawalChannel": "pindebit.atm.withdrawal",
            "pindebitCashbackChannel": "pindebit.cashback",
            "pindebitAuthorizationClearingChannel": "pindebit.auth.clr",
            "pindebitReversalChannel": "pindebit.rvs",
            "pindebitRefundChannel": "pindebit.refund",
            "clearingRepresentmentChannel": "auth.clr.representment",
            "originalCreditAuthCaptureChannel": "org.credit.auth.cap",
            "authClearingChargebackChannel": "auth.clr.chrg",
            "authClearingChargebackCompletedChannel": "auth.clr.chrg.compl",
            "pindebitChargebackChannel": "pindebit.chrg",
            "pindebitChargebackCompletedChannel": "pindebit.chrg.compl",
            "accountFundingAuthClearingChannel": "acc.fund.auth.clr",
            "pindebitRefundReversalChannel": "pindebit.refund.rvs",
            "originalCreditAuthPlusCaptureReversalChannel": "org.credit.auth.cap.rvs",
            "authorizationClearingChargebackReversalChannel": "auth.clr.chrg.rvs",
            "pindebitChargebackReversalChannel": "pindebit.chrg.rvs"
        }

Based on the type of the Marqeta event, the currency_code parameter is mapped dynamically.

For DBIT financial transactions the currency_code is read from the gpa_order object:

data.financialTransaction.transactionChannelId = data.mambuConfig.transactionChannels.authorizationClearingChannel + "." + data.transaction.gpa_order.currency_code

For CRDT financial transactions the currency_code is read from the transaction object:

data.financialTransaction.transactionChannelId = data.mambuConfig.transactionChannels.refundChannel + "." + data.transaction.currency_code;

Create custom fields

Follow these steps:

• Add a new custom field set in Mambu.
  
• Under the newly created custom field set, add the following custom fields.

The Custom Fields that need to be created and their type are in the table below.

MPO connector setup

Import the connector

Create an API key

You will need to create an API key and add it to the JIT Actionable and Informative Notifications Receiver processes.

API Key:

Add the key to the process:

Run the setup process

Open the Setup & Config folder and run the Connector setup process (Mambu + notifications)

Required parameters:

{
    "enableCustomInformation": "<boolean, switch on/off custom transaction fields>",
    "mambuUrl": "<Mambu Tenant Url>",
    "mambuUser": "<Mambu Api user name>",
    "mambuPassword": "<user password>",
    //Mambu transaction channels
    "originalCreditAuthorizationChannel": "<original Credit Authorization Channel id>",
    "refundAuthorizationClearingChannel": "<refund Authorization Clearing Channel id>",
    "authorizationClearingAtmWithdrawalChannel": "<authorization Clearing Atm Withdrawal Channel id>",
    "authorizationClearingCashbackChannel": "<authorization Clearing Cashback Channel id>",
    "authorizationClearingChannel": "<authorization Clearing Channel id>",
    "authorizationClearingQuasiCashChannel": "<authorization Clearing Quasi Cash Channel id>",
    "refundChannel": "<refund Channel id>",
    "pindebitChannel": "<pindebit Channel id>",
    "pindebitAtmWithdrawalChannel": "<pindebit atm withdrawal Channel id>",
    "pindebitCashbackChannel": "<pindebit cashback Channel id>",
    "pindebitAuthorizationClearingChannel": "<pindebit authorization clearing Channel id>",
    "pindebitReversalChannel" : "<pindebit reversal Channel id>",
    "clearingRepresentmentChannel": "<authorization clearing representment Channel>",
    "originalCreditAuthCaptureChannel": "<original credit authorizatin plus capture Channel>",
    "authClearingChargebackChannel": "<authorization clearing chargeback Channel >",
    "authClearingChargebackCompletedChannel": "<authorization clearing chargeback completed Channel >",
    "pindebitChargebackChannel": "<pindebit chargeback Channel >",
    "pindebitChargebackCompletedChannel":  "<pindebit chargeback completed Channel >",
    "accountFundingAuthClearingChannel": "<account funding authorization clearing Channel>",
    "pindebitRefundReversalChannel" : "<pindebit refund reversal Channel>",
    "originalCreditAuthPlusCaptureReversalChannel" : "<original credit auth plus capture reversal Channel>",
    "authorizationClearingChargebackReversalChannel": "<authorization clearing chargeback reversal Channel>",
    "pindebitChargebackReversalChannel": "<pindebit chargeback reversal Channel>"
    //Mambu custom fields
    "marqetaAquirerFeeCF": "<acquirer fee custom field id>",
    "marqetaBatchNumberCF": "<batch number custom field id>",
    "marqetaConversionRateCF": "<conversion rate custom field id>",
    "marqetaCrossBorderIssuerFeeCF": "<cross border issuer fee custom field id>",
    "marqetaCurConvCardholderFeeCF": "<currency conversion cardholder fee custom field id>",
    "marqetaCurConvIssuerFeeCF": "<currency conversion issuer fee custom field id>",
    "marqetaCustomFieldSetId": "<Mambu custom field set id>",
    "marqetaInterchangeFeeCF": "<interchange fee custom field id>",
    "marqetaIssuerBinCF": "<issuer BIN custom field id>",
    "marqetaIssuerFeeCF": "<issuer fee custom field id>",
    "marqetaMambuCustomerIdCF": "<customer id custom field id>",
    "marqetaOriginalAmountCF": "<original amount custom field id>",
    "marqetaOriginalCurrencyCF": "<original currency custom field id>",
    "marqetaPinDebitAssocFeeCF": "<PIN Debit association custom field id>",
    "marqetaSettlementDateCF": "<settlement date custom field id>",
    "marqetaSwitchFeeCF": "<switch fee custom field id>",
    "marqetaVisaTransactionIdCF": "<VISA transaction Id custom field id>",
    //Notifications config data
    "mambuTaskAssignedUser": "<Mambu task assigned user encodedKey>",
    "clearingNotifications": "<true/false>",
    "channel": "<task/zenDesk>",
    "webhookUrl": "<webhook Url for notifications>",
    "zenDeskApiKey": "<ZenDesk ApiKey>",
    "zenDeskGroupId": "<ZenDesk GroupId>",
    "zenDeskLogin": "<ZenDesk Login>",
    "zenDeskSubdomain": "<ZenDesk Subdomain>"
}

API gateway setup

You have two options for calling the JIT Actionable Receiver and the JIT Informative Notifications Receiver MPO processes:

1. Creating your own API Gateways.
2. Using the connector’s AWS API Gateways with Lambda functions.

Creating your own API gateways

You need to use the following details when calling the JIT Actionable Receiver and the JIT Informative Notifications Receiver processes via your own API Gateways:

• The HTTP method used for calling the process is POST.
• Call URL: {YOUR_MPO_ENVIRONMENT}-syncapi.mambuonline.com/api/JSON/{LOGIN}/{TIMESTAMP}{SIGNATURE}
  • {LOGIN}: Parameter has the value of the Login API Key created in MPO.
  • {TIMESTAMP}: The current unix timestamp.
  • {SIGNATURE}: Signatures are used to authenticate requests and are created based on time, API Key Secret and request data.

More information about signing your requests to MPO can be found in our MPO Sync API support article.

The payload to include with the request will look like this:

{
  "ops": [
    {
      "company_id": "string - ID of the company on which the connector is installed on MPO",
      "obj_id": "string - ID of the targeted process",
      "type": "create",
      "obj": "task",
      "data": "object - The payload expected by the MPO process"
    }
  ]
}

The MPO platform will only respond with a 200 HTTP code, so your API Gateway must be capable of mapping any error returned by MPO as a JSON body to the 402 HTTP code when responding to the Marqeta system.

JSON payload examples expected as input by the MPO processes JIT Actionable Receiver and JIT Informative Notification Receiver can be found in the GitLab repository provided when you purchase this connector or from your integration consultant.

More information about jit_funding messages can be found in the Marqeta documentation.

A. API Gateway requirements for the JIT Actionable Receiver

JIT Actionable Gateway will send any actionable messages received from the Marqeta platform to the JIT Actionable Receiver MPO process.

JIT Actionable Gateway will programmatically return the jit_funding object received from the JIT Actionable Receiver, to approve or deny the funding request.

A complete JIT Funding response includes the following elements:

• The appropriate HTTP response code (200 OK or 402 Payment Required).
• The jit_funding object as is received from the JIT Actionable Receiver.

JIT Actionable Receiver will respond to the JIT Actionable Gateway with the following elements:

• For approved requests:

{
  "jit_funding": {
    "token": "**YOUR JIT FUNDING REQUEST TOKEN**",
    "method": "pgfs.authorization",
    "user_token": "**YOUR USER TOKEN**",
    "memo": "Approved",
    "amount": 10.00
  }
}

• For rejected requests:

{
  "jit_funding": {
    "token": "**YOUR JIT FUNDING REQUEST TOKEN**",
    "method": "pgfs.authorization",
    "user_token": "**YOUR USER TOKEN**",
    "amount": 10.00,
    "decline_reason": "decline_reason",
    "tags": "Mambu error reason"
  }
}

More information about the jit_funding responses can be found here.

B. API Gateway requirements for the JIT Informative Notifications Receiver

JIT Informative Notifications Gateway will send to the JIT Informative Notifications Receiver MPO process the transactions received from the Marqeta platform. The events are received in batches as webhook notifications.

JIT Informative Notifications Gateway will only respond to the Marqeta platform with the appropriate HTTP response code (200 OK or 402 Payment Required).

JIT Informative Notifications Receiver will respond to the JIT Informative Notifications Gateway with the following elements:

• For accepted requests:

{
    "message": "Batch accepted!",
    "statusCode": 200
}

• For rejected requests:

{
     "message": "Batch rejected!",
    "statusCode": 402
}

If the JIT Informative Notifications Gateway does not respond with a 200 HTTP response code, the Marqeta platform will try to resend the notification.

Using our AWS API gateways

JIT Actionable Receiver entry point requires the creation of an API gateway with 2 Lambda functions as follows:

• 1 API gateway which handles the actionable events from Marqeta;
    - 1 Lambda function for the Basic Authentication;
    - 1 Lambda function used for triggering JIT Actionable Receiver and sending back the response to Marqeta;
  

JIT Informative Receiver entry point requires the creation of an API gateway with 2 Lambda functions as follows:

• 1 API gateway which handles the informative events from Marqeta;
    - 1 Lambda function for the Basic Authentication;
    - 1 Lambda function used for triggering the JIT Informative Receiver and for the Marqeta Digital Signature check

Please contact your Integration Consultant to assist you with the AWS configuration for the two API Gateways and their corresponding lambda functions.