> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mangopay.com/api-reference/direct-card-payins/direct-card-payin-object/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.
# The Direct Card PayIn object
> One-time payment using a tokenized card
### Description
Mangopay relies on the Direct Card PayIn to process one-time payments with a registered card. A Direct Card PayIn requires a `CardId`, obtained from the Card Registration object, Checkout SDK, or Vault SDK.
The Direct Card PayIn represents a one-time card payment. Different endpoints are required for [recurring](/api-reference/recurring-payin-registrations/create-recurring-payin-registration), [7-day preauthorized](/api-reference/preauthorizations/preauthorization-object), or [30-day preauthorized](/api-reference/extended-preauthorizations/extended-preauthorization-object) card payments, as well as to [validate a card without debiting it](/api-reference/card-validations/card-validation-object).
### Attributes
### Schema (`DirectCardPayInResponse`)
```yaml
components:
schemas:
Id:
type: string
description: >-
Max length: 128 characters (see [data
formats](/api-reference/overview/data-formats) for details)
The unique identifier of the object.
title: Id
Tag:
type: string
description: >-
Max. length: 255 characters
Custom data that you can add to this object, such as unique identifiers
in your system. To store multiple values, you can serialize them into a
single string, for example a JSON object:
`"{\"id_1\":AB123,\"id_2\":DE456}"`.
title: Tag
CreationDate:
type: integer
description: Unix timestamp (UTC) of the date and time the object was created.
title: CreationDate
AuthorId:
type: string
description: The unique identifier of the user at the source of the transaction.
title: AuthorId
CreditedUserId:
type: string
description: >-
**Default value:** The unique identifier of the owner of the credited
wallet.
The unique identifier of the user whose wallet is credited.
title: CreditedUserId
FlowDescriptorResponseBeneficiariesItems:
type: object
properties:
UserId:
type: string
description: >-
The unique identifier of the Natural User or Legal User declared as
a beneficiary of the pay-in.
title: FlowDescriptorResponseBeneficiariesItems
FlowDescriptorResponse:
type: object
properties:
FlowId:
type: string
description: >-
Unique identifier of the payment flow, used by Mangopay for internal
purposes.
Beneficiaries:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/FlowDescriptorResponseBeneficiariesItems'
description: >-
Max. length: 5 items
The list of up to 5 Natural or Legal Users declared as beneficiaries
of the pay-in, who must all be KYC/KYB verified when the pay-in
request is made. The pay-in also fails if the `Beneficiaries` array
contains nulled objects or invalid `UserId` values.
description: >
Information about the Owner beneficiaries targeted by the pay-in and its
subsequent transfers, who must all be KYC/KYB verified when the pay-in
request is made ([read more](/guides/payin-beneficiaries)).
If the `FlowDescriptor.Beneficiaries` is sent in the API request, then:
- The transaction's `CreditedWalletId` holder is disregarded in KYC/KYB
checks.
- **ALL** `UserId` values in the array must be one of:
- `OWNER` whose `KYCLevel` is `REGULAR`
- `PLATFORM`
The pay-in `Status` becomes `FAILED` with `ResultCode`
[002951](/errors/codes/002951) if at least one
`FlowDescriptor.Beneficiaries.UserId` is:
- `PAYER`
- `OWNER` whose `KYCLevel` is `LIGHT`
If the `FlowDescriptor.Beneficiaries` is not sent in the API request,
then the `CreditedWalletId` holder is subject to KYC/KYB checks. This
property is optional for backwards compatibility but is recommended for
all pay-in flows, even when the `CreditedWalletId` holder is a `PAYER`
or the same value as one of the `FlowDescriptor.Beneficiaries`.
title: FlowDescriptorResponse
Currency:
type: string
description: >-
**Allowed values:** The three-letter ISO 4217
code (EUR, GBP, etc.) of a supported currency (depends on feature, contract,
and activation settings).
The currency of the amount.
title: Currency
Amount:
type: integer
description: >-
The amount of the currency in its minor unit. For example, EUR 12.60
would be represented as `1260` whereas JPY 12 would be represented as
just `12`.
title: Amount
DirectCardPayInResponseDebitedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: Information about the debited funds.
title: DirectCardPayInResponseDebitedFunds
DirectCardPayInResponseCreditedFunds:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: >-
Information about the credited funds (`CreditedFunds` = `DebitedFunds` -
`Fees`).
title: DirectCardPayInResponseCreditedFunds
DirectCardPayInResponseFees:
type: object
properties:
Currency:
$ref: '#/components/schemas/Currency'
Amount:
$ref: '#/components/schemas/Amount'
description: >-
Information about the fees taken by the platform for this transaction
(and hence transferred to the Fees Wallet).
title: DirectCardPayInResponseFees
TransactionStatus:
type: string
description: |-
**Returned values:** `CREATED`, `SUCCEEDED`, `FAILED`
The status of the transaction.
title: TransactionStatus
ResultCode:
type: string
description: >-
The code indicating the result of the operation. This information is
mostly used to handle errors or for
filtering purposes.
title: ResultCode
ResultMessage:
type: string
description: The explanation of the result code.
title: ResultMessage
TransactionExecutionDate:
type: integer
description: >-
Unix timestamp (UTC) of the date and time the status changed to
`SUCCEEDED`, indicating that the transaction occurred. The statuses
`CREATED` and `FAILED` return an `ExecutionDate` of `null`.
title: TransactionExecutionDate
TransactionType:
type: string
description: |-
**Returned values:** `PAYIN`, `TRANSFER`, `CONVERSION`, `PAYOUT`
The type of the transaction.
title: TransactionType
TransactionNature:
type: string
description: >-
**Returned values:** `REGULAR`, `REPUDIATION`, `REFUND`, `SETTLEMENT`
The nature of the transaction, providing more information about the
context in which the transaction occurred:
- `REGULAR` – Relative to most of the transactions (pay-ins, payouts,
and transfers) in a usual workflow.
- `REPUDIATION` – Automatic withdrawal of funds from the platform's
repudiation wallet as part of the dispute process (when the user has
requested a chargeback).
- `REFUND` – Reimbursement of a transaction to the user (pay-in refund),
to a wallet (transfer refund), or of a payout (payout refund, only
initiated by Mangopay).
- `SETTLEMENT` – Transfer made to the repudiation wallet by the platform
to settle a lost dispute.
title: TransactionNature
SecureModeReturnURL:
type: string
description: >-
Max. length: 255 characters
The URL to which users are automatically returned after 3DS2 if it is
triggered (i.e., if the `SecureModeNeeded` parameter is set to `true`).
title: SecureModeReturnURL
AVSResult:
type: object
properties:
AVSResult:
type: string
description: >-
The result of the Address Verification System check (only available
for UK, US, and Canada).
description: Information regarding security and anti-fraud tools.
title: AVSResult
StatementDescriptor_22:
type: string
description: >-
Max. length: 22 characters; only alphanumeric and spaces
Custom description to appear on the user’s bank statement along with the
platform name. Different banks may show more or less information. See
the Customizing bank statement references
article for details.
title: StatementDescriptor_22
BrowserInfo:
type: object
properties:
AcceptHeader:
type: string
description: >-
The exact content of the HTTP accept headers as sent to the platform
from the end user's browser.
JavaEnabled:
type: boolean
description: >-
Whether or not the end user's browser has the ability to execute
Java.
Language:
type: string
description: >-
Format: Two-letter language code (ISO 639-1 alpha-2) followed by
two-letter country code (ISO 3166-1 alpha-2), separated by a hyphen
(example: `en-US`; pattern:`^[a-zA-Z]{2}(-[a-zA-Z]{2})?$`)
The language of the browser.
ColorDepth:
type: integer
description: >-
The value representing the depth of the screen's color palette for
displaying images, in bits per pixel.
ScreenHeight:
type: integer
description: The height of the screen in pixels.
ScreenWidth:
type: integer
description: The width of the screen in pixels.
TimeZoneOffset:
type: integer
description: The difference in minutes between the browser's timezone and UTC.
UserAgent:
type: string
description: The exact content of the HTTP User-Agent header.
JavascriptEnabled:
type: boolean
description: >-
Whether or not the end user's browser has the ability to execute
JavaScript.
required:
- AcceptHeader
- JavaEnabled
- Language
- ColorDepth
- ScreenHeight
- ScreenWidth
- TimeZoneOffset
- UserAgent
- JavascriptEnabled
description: >-
Information about the browser used by the end user (author) to perform
the payment.
title: BrowserInfo
IpAddress:
type: string
description: >-
The IP address of the end user initiating the transaction, in IPV4 or
IPV6 format.
title: IpAddress
Address:
type: object
properties:
AddressLine1:
type: string
description: The first line of the address.
AddressLine2:
type: string
description: The second line of the address.
City:
type: string
description: The city of the address.
Region:
type: string
description: Required if `Country` is US, CA, or MX. The region of the address.
PostalCode:
type: string
description: >-
The postal code of the address. The postal code can contain the
following characters: alphanumeric, dashes, and spaces.
Country:
type: string
description: >-
Format: Two-letter country code ([ISO 3166-1 alpha-2
format](/api-reference/overview/data-formats))
The country of the address.
description: The postal address.
title: Address
Billing_DefaultsShippingUser_Response:
type: object
properties:
FirstName:
type: string
description: The first name of the user.
LastName:
type: string
description: The last name of the user.
Address:
$ref: '#/components/schemas/Address'
description: >-
**Default values:** `FirstName`, `LastName`, and `Address` information
of the `Shipping` object if sent, otherwise of the `AuthorId` (if
address values present).
Information about the billing address.
title: Billing_DefaultsShippingUser_Response
Address_SubPropsRequired:
type: object
properties:
AddressLine1:
type: string
description: The first line of the address.
AddressLine2:
type: string
description: The second line of the address.
City:
type: string
description: The city of the address.
Region:
type: string
description: Required if `Country` is US, CA, or MX. The region of the address.
PostalCode:
type: string
description: >-
The postal code of the address. The postal code can contain the
following characters: alphanumeric, dashes, and spaces.
Country:
type: string
description: >-
Format: Two-letter country code ([ISO 3166-1 alpha-2
format](/api-reference/overview/data-formats))
The country of the address.
required:
- AddressLine1
- City
- PostalCode
- Country
description: The postal address.
title: Address_SubPropsRequired
Shipping_DefaultsBillingUser_Response:
type: object
properties:
FirstName:
type: string
description: The first name of the user.
LastName:
type: string
description: The last name of the user.
Address:
$ref: '#/components/schemas/Address_SubPropsRequired'
description: >-
**Default values:** `FirstName`, `LastName`, and `Address` information
of the `Billing` object if sent, otherwise of the `AuthorId` (if address
values present).
Information about the shipping address.
title: Shipping_DefaultsBillingUser_Response
PreferredCardNetwork:
type: string
description: >-
**Allowed values:** `VISA`, `MASTERCARD`, `CB`, `MAESTRO`
The card network to use, as chosen by the cardholder, in case of co-branded cards.
title: PreferredCardNetwork
PaymentCategory:
type: string
description: >-
**Default value:** `ECommerce`
**Allowed values:** `ECommerce`, `TelephoneOrder`
The channel through which the user provided their card details, used to
indicate mail-order and telephone-order (MOTO) payments:
- `ECommerce` – Payment received online.
- `TelephoneOrder` – Payment received via mail order or telephone order
(MOTO).
title: PaymentCategory
CardInfo:
type: object
properties:
BIN:
type: string
description: The bank identification number (BIN) of the card.
IssuingBank:
type: string
description: The name of the bank that issued the card.
IssuerCountryCode:
type: string
description: The country code of the card issuer.
Type:
type: string
description: The type of card (for example, `CREDIT` or `DEBIT`).
SubType:
type:
- string
- 'null'
description: The sub-type of the card, if available.
Brand:
type: string
description: The card brand (for example, `VISA` or `MASTERCARD`).
description: >-
Information about the card used for the transaction. If the information
or data is not available, `null` is returned.
title: CardInfo
AuthenticationResult:
type: object
properties:
AuthenticationType:
type:
- string
- 'null'
description: >-
**Returned values:** `CHALLENGE`, `FRICTIONLESS`,
`DIRECT_AUTHORIZATION`
The type of authentication:
- `CHALLENGE` – The issuer requested SCA to be enforced (for
example, using 3DS).
- `FRICTIONLESS` – The transaction was exempted from SCA because an
exemption was granted by the issuer.
- `DIRECT_AUTHORIZATION` – The transaction was sent to the issuer
for authorization without any frictionless or challenge (for
example, if SCA doesn't apply). A `null` value typically indicates
that authentication was not requested (for example, because the
request failed before being sent) or a decision was not received.
A `null` value typically indicates that authentication was not
requested (for example, because the request failed before being
sent) or a decision was not received.
description: >-
Information about the authentication result, based on the request made
by Mangopay and the decision of the issuer regarding the type of
authentication to be enforced (if applicable).
title: AuthenticationResult
DirectCardPayInResponse:
type: object
properties:
Id:
$ref: '#/components/schemas/Id'
Tag:
$ref: '#/components/schemas/Tag'
CreationDate:
$ref: '#/components/schemas/CreationDate'
AuthorId:
$ref: '#/components/schemas/AuthorId'
CreditedUserId:
$ref: '#/components/schemas/CreditedUserId'
FlowDescriptor:
$ref: '#/components/schemas/FlowDescriptorResponse'
DebitedFunds:
$ref: '#/components/schemas/DirectCardPayInResponseDebitedFunds'
description: Information about the debited funds.
CreditedFunds:
$ref: '#/components/schemas/DirectCardPayInResponseCreditedFunds'
description: >-
Information about the credited funds (`CreditedFunds` =
`DebitedFunds` - `Fees`).
Fees:
$ref: '#/components/schemas/DirectCardPayInResponseFees'
description: >-
Information about the fees taken by the platform for this
transaction (and hence transferred to the Fees Wallet).
Status:
$ref: '#/components/schemas/TransactionStatus'
ResultCode:
$ref: '#/components/schemas/ResultCode'
ResultMessage:
$ref: '#/components/schemas/ResultMessage'
ExecutionDate:
$ref: '#/components/schemas/TransactionExecutionDate'
Type:
$ref: '#/components/schemas/TransactionType'
Nature:
$ref: '#/components/schemas/TransactionNature'
CreditedWalletId:
type: string
description: The unique identifier of the credited wallet.
DebitedWalletId:
type: string
description: >-
The unique identifier of the debited wallet.
In the case of a pay-in, this value is always `null` since there is
no debited wallet.
PaymentType:
type: string
description: |-
**Returned values:** `CARD`
The payment type of the pay-in.
ExecutionType:
type: string
description: |-
**Returned values:** `DIRECT`
The execution type of the pay-in.
SecureMode:
type: string
description: >-
**Returned values:** `DEFAULT`, `FORCE`, `NO_CHOICE`
The mode applied for the 3DS2 protocol for CB, Visa, and Mastercard.
The options are:
- `DEFAULT` – Requests an exemption to strong customer
authentication (SCA), and thus a frictionless payment experience, if
allowed by your Mangopay contract and accepted by the issuer.
- `FORCE` – Requests SCA.
- `NO_CHOICE` – Leaves the choice to the issuer whether to allow for
a frictionless payment experience or to enforce SCA.
CardId:
type: string
description: >-
The unique identifier of the Card object, obtained during the card
registration process.
SecureModeReturnURL:
$ref: '#/components/schemas/SecureModeReturnURL'
SecureModeRedirectURL:
type: string
description: |-
Max. length: 255 characters
The URL to which to redirect the user to proceed to 3DS2 validation.
SecureModeNeeded:
type: boolean
description: Whether or not the `SecureMode` was used.
Culture:
type: string
description: >-
**Returned values:** One of the supported languages in the [ISO
639-1 format](/api-reference/overview/data-formats): DE, EN, ES, FR,
IT, NL, PL, PT.
The language in which the payment page is to be displayed.
SecurityInfo:
$ref: '#/components/schemas/AVSResult'
StatementDescriptor:
$ref: '#/components/schemas/StatementDescriptor_22'
BrowserInfo:
$ref: '#/components/schemas/BrowserInfo'
IpAddress:
$ref: '#/components/schemas/IpAddress'
Billing:
$ref: '#/components/schemas/Billing_DefaultsShippingUser_Response'
Shipping:
$ref: '#/components/schemas/Shipping_DefaultsBillingUser_Response'
Requested3DSVersion:
type: string
description: |-
**Returned values:** `V1`, `V2_1`
The 3DS protocol version to be applied to the transaction.
Applied3DSVersion:
type: string
description: |-
**Returned values:** `V1`, `V2_1`
The 3DS protocol version applied to the transaction.
PreferredCardNetwork:
$ref: '#/components/schemas/PreferredCardNetwork'
PaymentCategory:
$ref: '#/components/schemas/PaymentCategory'
CardInfo:
$ref: '#/components/schemas/CardInfo'
AuthenticationResult:
$ref: '#/components/schemas/AuthenticationResult'
title: DirectCardPayInResponse
```
### Related resources
#### [How to](/guides/payment-methods/card/direct/how-to)
Learn how to process a card payment
#### [Checkout SDK](/sdks/checkout)
Simplify one-time card payments with Checkout SDK
> One-time payment using a tokenized card