Skip to main content
Note
This feature requires additional activation steps. To learn more about this feature and activating it for your program, contact your Marqeta representative.
A Credit Program Gateway enables your system to make decisions on purchase transaction authorizations at transaction time. Your Program Gateway and Marqeta’s credit platform exchange messages called Gateway requests and Gateway responses, which contain data or decisions on transaction authorizations. For the complete endpoint reference, see Program Gateways.

​
Transaction process

An authorization request is a type of purchase transaction that occurs when a cardholder makes a purchase. The process for using a Program Gateway to approve or deny an authorization request involves a series of steps performed by the card network, Marqeta’s credit platform, and you.
Credit Program Gateway transaction process
When the cardholder attempts to make a payment using an account that is part of a credit program configured with a Program Gateway, the following process occurs:
1
The merchant sends a transaction authorization request to the card network.
2
The card network sends an authorization request to Marqeta’s credit platform.
3
Marqeta’s credit platform performs checks on program, authorization, and velocity controls, and the account’s available credit, to validate the authorization.
4
If the authorization is valid, Marqeta’s credit platform sends a Gateway request to your Program Gateway endpoint.
5
Your Program Gateway evaluates the Gateway request and makes a decision.
6
Your Program Gateway returns a Gateway response to Marqeta’s credit platform either approving or declining the transaction authorization.
7
If the authorization is approved, the Marqeta platform returns a response to the card network and sends the transaction to your webhook endpoint for validation.
8
The card network sends an authorization response to the merchant.

​
Configuring a Program Gateway

You must configure a Program Gateway for your credit program to exchange messages with Marqeta’s credit platform, which enables you to approve or decline a transaction authorization request. A Program Gateway is an endpoint hosted in your environment that is configured to receive messages sent by Marqeta’s credit platform. To create a Program Gateway, send a POST request to the /credit/programgateways endpoint. For the endpoint reference, see Create Program Gateway.

​
Gateway requests

A Gateway request is an actionable message sent by the Marqeta platform to your Program Gateway that requests permission to approve a specific transaction authorization. Because all Gateway requests are actionable, you must evaluate the request body in each message and respond.

​
Transaction events

To use your Program Gateway, your gateway endpoint must be set up to listen for and process the following transaction event types:
  • pgfs.authorization
  • pgfs.authorization.incremental
  • pgfs.original.credit.authorization
  • pgfs.original.credit.auth_plus_capture
  • pgfs.refund.authorization

​
Request body

A Gateway request body contains transaction data such as the transaction amount, associated user_token (embedded in the jit_funding object), MID, MCC, and more.
Note
The Program Gateway for credit programs is a similar concept to JIT Funding for debit programs and uses the jit_funding object. For more, see The jit_funding object.
The following example shows what could appear in a Program Gateway request. For more examples and the endpoint reference, see JIT Funding requests.
JSON
{
  "type": "authorization",
  "state": "PENDING",
  "token": "198d1132-b34e-4445-a5ca-2e0fe4a55e26",
  "user_token": "user-158634",
  "acting_user_token": "user-158634",
  "card_token": "card-158634",
  "gpa": {
    "currency_code": "USD",
    "ledger_balance": 252.93,
    "available_balance": 0.00,
    "credit_balance": 0.00,
    "pending_credits": 0.00,
    "balances": {
      "USD": {
        "currency_code": "USD",
        "ledger_balance": 252.93,
        "available_balance": 0.00,
        "credit_balance": 0.00,
        "pending_credits": 0.00
      }
    }
  },
  "gpa_order": {
    "token": "b849f8a2-77a6-4745-bbb3-1dd8710427fa",
    "amount": 29.74,
    "transaction_token": "198d1132-b34e-4445-a5ca-2e0fe4a55e26",
    "state": "PENDING",
    "funding": {
      "amount": 29.74,
      "source": {
        "type": "programgateway",
        "token": "**********6a19",
        "active": true,
        "name": "jit funding source name",
        "is_default_account": false,
        "created_time": "2022-11-09T09:36:09Z",
        "last_modified_time": "2023-01-15T19:38:55Z"
      }
    },
    "funding_source_token": "**********6a19",
    "jit_funding": {
      "token": "0b199f94-2d5c-4fc4-9357-be998eaeebfd",
      "method": "pgfs.authorization",
      "user_token": "user-158634",
      "acting_user_token": "user-158634",
      "amount": 29.74
    },
    "user_token": "user-158634",
    "currency_code": "USD"
  },
  "created_time": "2022-09-25T23:41:25Z",
  "user_transaction_time": "2022-09-25T23:41:25Z",
  "amount": 29.74,
  "currency_code": "USD",
  "network": "MASTERCARD",
  "card_acceptor": {
    "mid": "4445001899609",
    "mcc": "5411",
    "name": "WHOLEFDS EGW 101",
    "city": "EDGEWATER",
    "state": "NJ",
    "postal_code": "07020",
    "country_code": "USA"
  },
  "acquirer": {
         "institution_country": "840",
         "institution_id_code": "375321467",
         "retrieval_reference_number": "526051868288",
         "system_trace_audit_number": "676127"
  },
  "fraud": {
         "network": {
             "transaction_risk_score": 86,
             "account_risk_score": 2
         }
  },
  "pos": {
         "pan_entry_mode": "MAG_STRIPE",
         "pin_entry_mode": "TRUE",
         "terminal_id": "TR100000",
         "terminal_attendance": "ATTENDED",
         "card_holder_presence": false,
         "card_presence": false,
         "partial_approval_capable": false,
         "purchase_amount_only": false,
         "is_recurring": false
  }
}

​
Gateway responses

A Gateway response is a message sent by your Program Gateway to Marqeta’s credit platform that approves or declines the transaction authorization sent in the Gateway request.

​
Approval and decline codes

Use standard HTTP response codes to approve or decline Gateway requests.
DecisionResponse code
Approve200 OK
Decline402 Request Failed

​
Response body

In the Gateway response body, you must include the original jit_funding object from the Gateway request, regardless of whether you approved or declined the transaction authorization.

​
Response time limit

Important
The maximum response time is 2000 milliseconds.
You are given 2000 milliseconds to evaluate and respond to each Gateway request, otherwise the transaction is automatically approved. Marqeta’s credit platform sends the approval to the card network, which completes the transaction authorization.

​
Decline reasons

If you decline the transaction authorization, you can include a decline reason in your Gateway response. In addition, you can inject custom metadata into each response. Messages sent to the Marqeta platform must use the HTTPS protocol. Possible decline reasons:
  • DUPLICATE_TRANSACTION
  • INVALID_AMOUNT
  • INVALID_CARD
  • INVALID_MERCHANT
  • REVOCATION_AUTHORIZATION_ORDER
  • REVOCATION_ALL_AUTHORIZATION_ORDER
  • SOFT_DECLINE_AUTHENTICATION_REQUIRED
  • STOP_PAYMENT
  • SUSPECTED_FRAUD
  • TRANSACTION_COUNT_LIMIT_EXCEEDED
  • TRANSACTION_NOT_PERMITTED
To determine which decline reason is most appropriate, contact your Marqeta representative.

​
Decision outcomes

The following are the possible scenarios and outcomes for transaction authorization decisions. Note that Commando Mode cannot be used.
Marqeta decisionProgram Gateway decisionFinal decision
ApproveApproveApprove
ApproveDeclineDecline
ApproveMissed response

Any non-402 response		Approve

​
Webhook event notifications

Marqeta sends webhook notifications of the transaction authorizations that you approved or declined to your webhook endpoint. You must have already configured a webhook to capture credit.* events. Receiving these webhooks is confirmation that these transaction authorizations made an appropriate impact on the account ledger. For more on events, see Credit journal entry events. For more on subscribing to webhook notifications, see the About Webhooks tutorial.

Related topics

Program GatewaysProgram Gateway Funding SourcesCredit Programs in the Marqeta DashboardImplementing Your Credit ProgramCredit in the Marqeta Dashboard