POST/
Use this endpoint to create a program transfer. Add the program transfer details to the body of the request in JSON format.
Include either user_token or business_token in the message body to specify the account holder whose general purpose account (GPA) will be debited by the program transfer. The user or business must already exist.
Note
If the GPA has insufficient funds to cover both the amount of the program transfer and all attached fees, then no funds are transferred.
If the GPA has insufficient funds to cover both the amount of the program transfer and all attached fees, then no funds are transferred.
Request body
| Fields | Description |
|---|---|
| amount decimal Required | Amount of program transfer. Allowable Values: decimal Format: 0.00 |
| business_token string Optional | Unique identifier of the business. Pass either a business_token or a user_token, not both.Send a GET request to /businesses to retrieve business tokens.Allowable Values: 1–36 chars |
| currency_code string Required | Three-digit ISO 4217 currency code. Allowable Values: Valid three-digit ISO 4217 currency code |
| fees array of objects Optional | Contains attributes that define characteristics of one or more fees. This array is returned in the response when it is included in the request. Allowable Values: One or more fee objects |
| fees[].memo string Optional | Additional text describing the fee. Allowable Values: 1–255 chars |
| fees[].overrideAmount decimal Optional | Dynamic fee amount that overrides the fee.amount field value.Allowable Values: decimal Format: 0.00 |
| fees[].tags string Optional | Descriptive metadata about the fee. Allowable Values: 255 char max |
| fees[].token string Required | Unique identifier of the fee. Allowable Values: 1–36 chars |
| memo string Optional | Memo or note describing the program transfer. Allowable Values: 1–99 chars |
| tags string Optional | Comma-delimited list of tags describing the program transfer. Allowable Values: 1–255 chars |
| token string Optional | Unique identifier of the program transfer. If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated. Allowable Values: 1–36 chars |
| type_token string Required | Unique identifier of the program transfer type. Send a GET request to /programtransfers/types to retrieve program transfer type tokens.Allowable Values: 1–36 chars |
| user_token string Optional | Unique identifier of the user. Pass either a user_token or a business_token, not both.Send a GET request to /users to retrieve business tokens.Allowable Values: 1–36 chars |
Sample request body
JSON
{
"token": "my_program_transfer_01",
"amount": 1,
"tags": "tag1, tag2, tag3",
"memo": "This is my program transfer",
"type_token": "my_program_transfer_type_01",
"user_token": "my_user_01",
"currency_code": "USD"
}
Response body
| Fields | Description |
|---|---|
| amount decimal Returned | Amount of program transfer. Allowable Values: decimal Format: 0.00 |
| business_token string Conditionally returned | Unique identifier of the business account holder. Returned if user_token is not specified.Allowable Values: 1–36 chars |
| created_time datetime Conditionally returned | Date and time when the program transfer object was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| currency_code string Returned | Three-digit ISO 4217 currency code. Allowable Values: Valid three-digit ISO 4217 currency code |
| fees array of objects Conditionally returned | Contains attributes that define characteristics of one or more fees. Allowable Values: Valid array of one or more fees objects |
| fees[].fee object Returned | Contains details about the fee. Allowable Values: amount, created_time, currency_code, last_modified_time, name, tags, token |
| fees[].fee.amount decimal Returned | Amount of the fee. Allowable Values: decimal Format: 0.00 |
| fees[].fee.created_time datetime Returned | Date and time when the fees object was created, in UTC.Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| fees[].fee.currency_code string Returned | Three-digit ISO 4217 currency code. Allowable Values: Valid three-digit ISO 4217 currency code |
| fees[].fee.last_modified_time datetime Returned | Date and time when the fees object was last modified, in UTC.Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| fees[].fee.name string Returned | Name of the fee. Allowable Values: 50 char max |
| fees[].fee.tags string Conditionally returned | Descriptive metadata about the fee. Allowable Values: 255 char max |
| fees[].fee.token string Returned | Unique identifier of the fees object.Allowable Values: Existing fees object token |
| fees[].memo string Conditionally returned | Additional text describing the fee. Allowable Values: 1–255 chars |
| fees[].overrideAmount decimal Conditionally returned | Dynamic fee amount that overrides the fee.amount field value.Allowable Values: decimal Format: 0.00 |
| fees[].tags string Conditionally returned | Descriptive metadata about the fee. Allowable Values: 255 char max |
| fees[].token string Returned | Unique identifier of the fee. Allowable Values: 1–36 chars |
| fees[].transaction_token string Returned | Unique identifier of the fee transaction. Allowable Values: 36 char max |
| jit_funding object Conditionally returned | Contains information about the JIT Funding load event, in which funds are loaded into an account. This object is returned if your program uses JIT Funding. Allowable Values: acting_user_token, address_verification, amount, balances, business_token, decline_reason, incremental_authorization_jit_funding_tokens, memo, method, original_jit_funding_token, tags, token, user_token |
| jit_funding.acting_user_token string Conditionally returned | User who conducted the transaction. Can be a child user configured to share its parent’s account balance. Allowable Values: 36 char max |
| jit_funding.address_verification object Conditionally returned | Contains address verification data used to make JIT Funding decisions. Allowable Values: gateway, issuer, request |
| jit_funding.address_verification.gateway object Conditionally returned | Contains address verification data consisting of address data entered by the cardholder, address data held by the Marqeta platform, and an assertion by the Marqeta platform as to whether the two sets of data match. Allowable Values: on_file, response |
| jit_funding.address_verification.gateway.on_file object Conditionally returned | Contains address verification information. Allowable Values: postal_code, street_address, zip |
| jit_funding.address_verification.gateway.on_file.postal_code string Conditionally returned | Postal code of the address. Allowable Values: 10 char max |
| jit_funding.address_verification.gateway.on_file.street_address string Conditionally returned | Street name and number of the address. Allowable Values: 40 char max |
| jit_funding.address_verification.gateway.on_file.zip string Conditionally returned | United States ZIP code of the address. Allowable Values: 10 char max |
| jit_funding.address_verification.gateway.response object Conditionally returned | Response codes and memos for account name verification, address verification, card security verification, and transactions. Allowable Values: additional_information, code, memo |
| jit_funding.address_verification.gateway.response.additional_information string Conditionally returned | Additional information about the transaction, such as velocity control details. This field is returned in transaction response objects only. It is not returned in address verification or card security verification response objects. Allowable Values: 255 char max |
| jit_funding.address_verification.gateway.response.code string Returned | Four-digit response code for address verification, card security code verification, or transactions. For account name verification, the four digits correspond with assertions that the first, middle, last, and full name of the cardholder on the Marqeta platform match the data provided by the cardholder. - 0 indicates no validation was performed- 1 indicates the match was unsuccessful (not matched)- 2 indicates the match was partial- 3 indicates the match was exactFor example: Code / First Name / Middle Name / Last Name / Full Name 0000 / Not validated / Not validated / Not validated / Not validated1111 / Not matched / Not matched / Not matched / Not matched3333 / Exact match / Exact match / Exact match / Exact match1232 / Not matched / Partial match / Exact match / Partial matchFor address verification responses, the code is an assertion by the Marqeta platform as to whether its address verification data matches that provided by the cardholder: Code / Address / Postal Code 0000 / Match / Match0001 / Match / Not matched0100 / Not matched / Match0101 / Not matched / Not matched0200 / Data not present / Match0201 / Data not present / Not matched0002 / Match / Data not present0102 / Not matched / Data not present0303 / Not validated / Not validatedFor card security verification, the code indicates whether the verification check passed and can have these possible values: - 0000 – Passed- 0001 – Did not passFor a transaction, the code describes the outcome of the attempted transaction. For the full list of transaction codes, see Transaction response codes. Allowable Values: Four-digit code |
| jit_funding.address_verification.gateway.response.memo string Returned | Additional text that describes the response. Allowable Values: 255 char max |
| jit_funding.address_verification.issuer object Conditionally returned | Contains address verification data consisting of address data entered by the cardholder, address data held by the Marqeta platform, and an assertion by the Marqeta platform as to whether the two sets of data match. Allowable Values: on_file, response |
| jit_funding.address_verification.issuer.on_file object Conditionally returned | Contains address verification information. Allowable Values: postal_code, street_address, zip |
| jit_funding.address_verification.issuer.on_file.postal_code string Conditionally returned | Postal code of the address. Allowable Values: 10 char max |
| jit_funding.address_verification.issuer.on_file.street_address string Conditionally returned | Street name and number of the address. Allowable Values: 40 char max |
| jit_funding.address_verification.issuer.on_file.zip string Conditionally returned | United States ZIP code of the address. Allowable Values: 10 char max |
| jit_funding.address_verification.issuer.response object Conditionally returned | Response codes and memos for account name verification, address verification, card security verification, and transactions. Allowable Values: additional_information, code, memo |
| jit_funding.address_verification.issuer.response.additional_information string Conditionally returned | Additional information about the transaction, such as velocity control details. This field is returned in transaction response objects only. It is not returned in address verification or card security verification response objects. Allowable Values: 255 char max |
| jit_funding.address_verification.issuer.response.code string Returned | Four-digit response code for address verification, card security code verification, or transactions. For account name verification, the four digits correspond with assertions that the first, middle, last, and full name of the cardholder on the Marqeta platform match the data provided by the cardholder. - 0 indicates no validation was performed- 1 indicates the match was unsuccessful (not matched)- 2 indicates the match was partial- 3 indicates the match was exactFor example: Code / First Name / Middle Name / Last Name / Full Name 0000 / Not validated / Not validated / Not validated / Not validated1111 / Not matched / Not matched / Not matched / Not matched3333 / Exact match / Exact match / Exact match / Exact match1232 / Not matched / Partial match / Exact match / Partial matchFor address verification responses, the code is an assertion by the Marqeta platform as to whether its address verification data matches that provided by the cardholder: Code / Address / Postal Code 0000 / Match / Match0001 / Match / Not matched0100 / Not matched / Match0101 / Not matched / Not matched0200 / Data not present / Match0201 / Data not present / Not matched0002 / Match / Data not present0102 / Not matched / Data not present0303 / Not validated / Not validatedFor card security verification, the code indicates whether the verification check passed and can have these possible values: - 0000 – Passed- 0001 – Did not passFor a transaction, the code describes the outcome of the attempted transaction. For the full list of transaction codes, see Transaction response codes. Allowable Values: Four-digit code |
| jit_funding.address_verification.issuer.response.memo string Returned | Additional text that describes the response. Allowable Values: 255 char max |
| jit_funding.address_verification.request object Conditionally returned | Contains address verification information. Allowable Values: postal_code, street_address, zip |
| jit_funding.address_verification.request.postal_code string Conditionally returned | Postal code of the address. Allowable Values: 10 char max |
| jit_funding.address_verification.request.street_address string Conditionally returned | Street name and number of the address. Allowable Values: 40 char max |
| jit_funding.address_verification.request.zip string Conditionally returned | United States ZIP code of the address. Allowable Values: 10 char max |
| jit_funding.jit_account_name_verification object Conditionally returned | Contains account name verification data used to make JIT Funding decisions from one of the following objects: - The gateway object, which contains account name verification data from your JIT Funding gateway.- The issuer object, which contains account name verification data from the Marqeta platform.- The request object, which contains account name verification data as it appears in a JIT Funding request.Allowable Values: gateway, issuer, request |
| jit_funding.jit_account_name_verification.gateway object Conditionally returned | Contains account name verification data used to make JIT Funding decisions. Allowable Values: first_name, last_name, middle_name |
| jit_funding.jit_account_name_verification.issuer object Conditionally returned | Contains account name verification data used to make JIT Funding decisions. Allowable Values: first_name, last_name, middle_name |
| jit_funding.jit_account_name_verification.request object Conditionally returned | Contains account name verification data used to make JIT Funding decisions. Allowable Values: first_name, last_name, middle_name |
| jit_funding.amount decimal Returned | Requested amount of funding. Allowable Values: 0 min Format: 0.00 |
| jit_funding.balances object Conditionally returned | Contains the GPA’s balance details. Allowable Values: available_balance, balances, cached_balance, credit_balance, currency_code, impacted_amount, last_updated_time, ledger_balance, pending_credits |
| jit_funding.business_token string Conditionally returned | Holder of the business account that was funded. Allowable Values: 36 char max |
| jit_funding.decline_reason string Conditionally returned | Reason why the transaction was declined. Allowable Values: AMOUNT_LIMIT_EXCEEDED, BLOCKED_BY_CARDHOLDER, BLOCKED_BY_ISSUER, BLOCKED_MERCHANT_BY_CARDHOLDER, CARD_NOT_ACTIVE, CARDHOLDER_NOT_ACTIVE, CLOSED_ACCOUNT, DUPLICATE_TRANSACTION, EXPIRED_CARD, INSUFFICIENT_FUNDS, INVALID_AMOUNT, INVALID_CARD, INVALID_MERCHANT, NO_CHECKING_ACCOUNT, NO_CREDIT_ACCOUNT, NO_SAVINGS_ACCOUNT, REVOCATION_ALL_AUTHORIZATION_ORDER, REVOCATION_AUTHORIZATION_ORDER, SOFT_DECLINE_AUTHENTICATION_REQUIRED, SOFT_DECLINE_PIN_REQUIRED, STOP_PAYMENT, SUSPECTED_FRAUD, TRANSACTION_COUNT_LIMIT_EXCEEDED, TRANSACTION_NOT_PERMITTED |
| jit_funding.incremental_authorization_jit_funding_tokens array of strings Conditionally returned | Array of tokens referencing the JIT Funding tokens of all previous associated incremental authorization JIT Funding requests. Useful for ascertaining the final transaction amount when the original amount was incremented. Allowable Values: Existing incremental authorization JIT Funding tokens |
| jit_funding.memo string Conditionally returned | Additional information that describes the JIT Funding transaction. Allowable Values: 99 char max |
| jit_funding.method string Returned | JIT Funding response type. See The jit_funding object for the purpose, funding event type, and description of each method. Allowable Values: pgfs.adjustment.credit, pgfs.adjustment.debit, pgfs.authorization, pgfs.authorization.account_verification, pgfs.authorization.capture, pgfs.authorization.capture.chargeback, pgfs.authorization.capture.chargeback.reversal, pgfs.authorization.incremental, pgfs.authorization.reversal, pgfs.authorization.standin, pgfs.auth_plus_capture, pgfs.auth_plus_capture.standin, pgfs.balanceinquiry, pgfs.billpayment, pgfs.billpayment.capture, pgfs.billpayment.reversal, pgfs.directdeposit.credit, pgfs.directdeposit.credit.reversal, pgfs.directdeposit.debit, pgfs.directdeposit.debit.reversal, pgfs.dispute.credit, pgfs.dispute.debit, pgfs.force_capture, pgfs.network.load, pgfs.original.credit.authorization, pgfs.original.credit.auth_plus_capture, pgfs.pindebit.chargeback, pgfs.pindebit.chargeback.reversal, pgfs.product.inquiry, pgfs.refund, pgfs.refund.authorization, pgfs.refund.authorization.reversal |
| jit_funding.original_jit_funding_token string Conditionally returned | Unique identifier of the first associated JIT Funding message. Useful for correlating related JIT Funding messages (that is, those associated with the same GPA order). Not included in the first of any set of related messages. Allowable Values: 36 char max |
| jit_funding.tags string Conditionally returned | Customer-defined tags related to the JIT Funding transaction. Allowable Values: 255 char max |
| jit_funding.token string Returned | Existing JIT Funding token matching the funding.gateway_log.transaction_id field of the associated GPA order.NOTE: The transaction_id field updates if a subsequent JIT Funding message associated with that GPA order is sent. If multiple JIT Funding messages are associated with the same GPA order, the transaction_id field matches the token of the most recent message.Allowable Values: 36 char max |
| jit_funding.user_token string Returned | Holder of the user account that was funded. Allowable Values: 36 char max |
| memo string Conditionally returned | Additional description of the program transfer. Allowable Values: 1–99 chars |
| tags string Conditionally returned | Comma-delimited list of tags describing the program transfer. Allowable Values: 1–255 chars |
| token string Conditionally returned | Unique identifier of the program transfer. Allowable Values: 1–36 chars |
| transaction_token string Returned | Unique identifier of the transaction. Allowable Values: Existing transaction token |
| type_token string Returned | Unique identifier of the program transfer type. Allowable Values: 1–36 chars |
| user_token string Conditionally returned | Unique identifier of the user account holder. Returned if business_token is not specified.Allowable Values: 1–36 chars |
Sample response body
JSON
{
"token": "my_program_transfer_01",
"type_token": "my_program_transfer_type_01",
"user_token": "my_user_01",
"transaction_token": "169",
"currency_code": "USD",
"amount": 1,
"memo": "This is my program transfer",
"tags": "tag1, tag2, tag3",
"created_time": "2023-03-11T20:58:30Z"
}