Create a Recurring PayIn Registration (PayPal)

POST /v2.01/{ClientId}/recurringpayinregistrations

REST

{
    "AuthorId": "user_m_01J9KR16BG7EDC8RNEY2M18EXK",
    "CreditedWalletId": "wlt_m_01J9KR4A7BH8KVE4PG6DTNS817",
    "FirstTransactionDebitedFunds": {
        "Currency": "EUR",
        "Amount": 10000
    },
    "FirstTransactionFees": {
        "Currency": "EUR",
        "Amount": 1000
    },
    "Billing": {
        "FirstName": "Ofelia",
        "LastName": "Kilback",
        "Address": {
            "AddressLine1": "8151 Sipes Turnpike",
            "AddressLine2": "Garfield Meadows",
            "City": "Paris",
            "Region": "Île-de-France",
            "PostalCode": "75001",
            "Country": "FR"
        }
    },
    "Shipping": {
        "FirstName": "Alex",
        "LastName": "Smith",
        "Address": {
            "AddressLine1": "6 rue de la Cité",
            "AddressLine2": "Appartement 3",
            "City": "Paris",
            "Region": "île-de-france",
            "PostalCode": "75003",
            "Country": "FR"
        }
    },
    "PaymentType": "PAYPAL"
}

200

{
    "Id": "recpayinreg_wt_c1fb7e3f-8204-4427-9251-df886fbb4e42",
    "Status": "CREATED",
    "ResultCode": null,
    "ResultMessage": null,
    "CurrentState": {
        "PayinsLinked": 0,
        "CumulatedDebitedAmount": {
            "Currency": "EUR",
            "Amount": 0
        },
        "CumulatedFeesAmount": {
            "Currency": "EUR",
            "Amount": 0
        },
        "LastPayinId": null
    },
    "RecurringType": "CUSTOM",
    "TotalAmount": null,
    "CycleNumber": null,
    "AuthorId": "user_m_01J9KR16BG7EDC8RNEY2M18EXK",
    "CardId": null,
    "CreditedUserId": null,
    "CreditedWalletId": "wlt_m_01J9KR4A7BH8KVE4PG6DTNS817",
    "Billing": {
        "FirstName": "Ofelia",
        "LastName": "Kilback",
        "Address": {
            "AddressLine1": "8151 Sipes Turnpike",
            "AddressLine2": "Garfield Meadows",
            "City": "Paris",
            "Region": "Île-de-France",
            "PostalCode": "75001",
            "Country": "FR"
        }
    },
    "Shipping": {
        "FirstName": "Alex",
        "LastName": "Smith",
        "Address": {
            "AddressLine1": "6 rue de la Cité",
            "AddressLine2": "Appartement 3",
            "City": "Paris",
            "Region": "île-de-france",
            "PostalCode": "75003",
            "Country": "FR"
        }
    },
    "EndDate": null,
    "Frequency": null,
    "FixedNextAmount": false,
    "FractionedPayment": false,
    "FreeCycles": 0,
    "FirstTransactionDebitedFunds": {
        "Currency": "EUR",
        "Amount": 10000
    },
    "FirstTransactionFees": {
        "Currency": "EUR",
        "Amount": 1000
    },
    "NextTransactionDebitedFunds": null,
    "NextTransactionFees": null,
    "Migration": false,
    "PaymentType": "PAYPAL"
}

Note – Only one registration per user on PayPal

On PayPal, only one recurring pay-in registration can be used per UserId. You can end a user’s existing registration object to create a new one with the same user.

Body parameters

AuthorId · string · required

The unique identifier of the user at the source of the transaction.

CreditedWalletId · string · required

The unique identifier of the credited wallet.

FirstTransactionDebitedFunds · object · required

The amount of the first recurring pay-in.
This value can be different from the NextTransactionDebitedFunds

Show properties

Currency · string · required

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 debited funds.

Amount · integer · required

An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).

FirstTransactionFees · object · required

The fees of the first recurring pay-in.
This amount can be different from the NextTransactionDebitedFunds.

Show properties

Currency · string · required

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 fees.

Amount · integer · required

An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).

Billing · object

Information about the end user’s billing address.

Show properties

FirstName · string

The first name of the user.

LastName · string

Max. length: 100 characters

The last name of the user.

Address · object

Information about the billing address.

Show properties

AddressLine1 · string · required

Max. length: 255 characters

The first line of the address.

AddressLine2 · string

Max. length: 255 characters

The second line of the address.

City · string

Max. length: 255 characters

The city of the address.

Region · string

Max. length: 255 characters

Required if Country is US, CA, or MX.

The region of the address.

PostalCode · string · required

Max. length: 255 characters

The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces.

Country · string · required

Format: Two-letter country code (ISO 3166-1 alpha-2 format)

The country of the address.

Shipping · object

Information about the end user’s shipping address.

Show properties

FirstName · string

The first name of the user.

LastName · string

Max. length: 100 characters

The last name of the user.

Address · object · required

Information about the shipping address.

Show properties

AddressLine1 · string · required

Max. length: 255 characters

The first line of the address.

AddressLine2 · string

Max. length: 255 characters

The second line of the address.

City · string · required

Max. length: 255 characters

The city of the address.

Region · string

Max. length: 255 characters

Required if Country is US, CA, or MX.

The region of the address.

PostalCode · string · required

Max. length: 255 characters

The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces.

Country · string · required

Format: Two-letter country code (ISO 3166-1 alpha-2 format)

The country of the address.

FixedNextAmount · boolean

For PayPal recurring registrations, this value is ignored if sent and automatically returned false. However, you can specify NextTransactionDebitedFunds and NextTransactionFees to set up a fixed-amount recurrence.

NextTransactionDebitedFunds · object

The amount of the subsequent recurring pay-ins.

Show properties

Currency · string · required

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 debited funds.

Amount · integer · required

An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).

NextTransactionFees · object

The fees of the subsequent recurring pay-ins.

Show properties

Currency · string · required

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 fees.

Amount · integer

An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).

PaymentType · string

Allowed values: CARD_DIRECT, PAYPAL

Default value: CARD_DIRECT

The type of recurring pay-in registration (which must correspond to the pay-ins requested against it).

Note: Multiple active CARD_DIRECT registrations can exist for a user, but only one PAYPAL registration.

ProfilingAttemptReference · string

The unique reference generated for the profiling session, used by the fraud prevention solution to produce recommendations for the transaction using the profiling data.

Note: Parameter not returned by the API. Profiling feature available on request – contact Mangopay via the Dashboard for more information.

Responses

200

Id · string

Max length: 128 characters (see data formats for details)

The unique identifier of the object.

Status · string

Returned values: CREATED, AUTHENTICATION_NEEDED, IN_PROGRESS, ENDED

The status of the recurring registration for PayPal:

• CREATED – The recurring registration was created, but no recurring pay-in has yet been made.
• AUTHENTICATION_NEEDED – A customer-initiated transaction (CIT) has been initiated against the registration but not authenticated. Note that there is no re-authentication process with PayPal: this status is only returned after the CIT is initiated but not yet successful.
• IN_PROGRESS – The CIT has was successful and subsequent merchant-initiated transactions (MIT) can be requested.
• ENDED – The registration can no longer be modified nor reused. A new one can be created for the same user.

ResultCode · string

The code indicating the result of the operation. This information is mostly used to handle errors or for filtering purposes.

ResultMessage · string

The explanation of the result code.

CurrentState · object

Information about the recurring pay-ins related to the registration object.

Note: If the LastPayinId references a transaction older than 13 months, it may have been archived.

Show properties

PayinsLinked · integer

The number of recurring pay-ins already made for the registration object.

CumulatedDebitedAmount · object

The sum of the DebitedFunds amounts of the recurring pay-ins made for the registration.

Show properties

Currency · string

Returned 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 debited funds.

Amount · integer

An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).

CumulatedFeesAmount · object

The sum of the Fees amounts of the recurring pay-ins made for the registration.

Show properties

Currency · string

Returned 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 fees.

Amount · integer

An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).

LastPayinId · string

The unique identifier of the last recurring pay-in made for the registration.

RecurringType · string

Returned values: CUSTOM

For PayPal recurring registrations, this value is always CUSTOM.

TotalAmount · object

For PayPal recurring registrations, this value is returned null.

CycleNumber · integer

For PayPal recurring registrations, this value is returned null.

AuthorId · string

The unique identifier of the user at the source of the transaction.

CardId · string

For PayPal recurring registrations, this value is returned null.

CreditedUserId · string

Default value: The unique identifier of the owner of the credited wallet.

The unique identifier of the user whose wallet is credited.

CreditedWalletId · string

The unique identifier of the credited wallet.

Billing · object

Default value: FirstName, LastName, and Address information of the Shipping object if any, otherwise the user (author).

Information about the end user billing address. If left empty, the default values will be automatically taken into account.

Show properties

FirstName · string

The first name of the user.

LastName · string

Max. length: 100 characters

The last name of the user.

Address · object

Information about the billing address.

Show properties

AddressLine1 · string

Max. length: 255 characters

The first line of the address.

AddressLine2 · string

Max. length: 255 characters

The second line of the address.

City · string

Max. length: 255 characters

The city of the address.

Region · string

Max. length: 255 characters

The region of the address. This field is optional except if the Country is US, CA, or MX.

PostalCode · string

Max. length: 255 characters

The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces.

Country · string

Format: Two-letter country code (ISO 3166-1 alpha-2 format)

The country of the address.

Shipping · object

Information about the end user’s shipping address.

Show properties

FirstName · string

The first name of the user.

LastName · string

Max. length: 100 characters

The last name of the user.

Address · object

Information about the shipping address.

Show properties

AddressLine1 · string

Max. length: 255 characters

The first line of the address.

AddressLine2 · string

Max. length: 255 characters

The second line of the address.

City · string

Max. length: 255 characters

The city of the address.

Region · string

Max. length: 255 characters

The region of the address. This field is optional except if the Country is US, CA, or MX.

PostalCode · string

Max. length: 255 characters

The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces.

Country · string

Format: Two-letter country code (ISO 3166-1 alpha-2 format)

The country of the address.

EndDate · Unix timestamp

For PayPal recurring registrations, this value is returned null.

Frequency · string

For PayPal recurring registrations, this value is returned null.

FixedNextAmount · boolean

For PayPal recurring registrations, this value is ignored if sent and automatically returned false. However, you can specify NextTransactionDebitedFunds and NextTransactionFees to set up a fixed-amount recurrence.

FractionedPayment · boolean

For PayPal recurring registrations, this value is returned null.

FreeCycles · integer

For PayPal recurring registrations, this value is returned 0.

FirstTransactionDebitedFunds · object

The amount of the first recurring pay-in.
This value can be different from the NextTransactionDebitedFunds

Show properties

Currency · string

Returned 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 debited funds.

Amount · integer

An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).

FirstTransactionFees · object

The fees of the first recurring pay-in.
This amount can be different from the NextTransactionDebitedFunds.

Show properties

Currency · string

Returned 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 fees.

Amount · integer

An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).

NextTransactionDebitedFunds · object

The amount of the subsequent recurring pay-ins.

Show properties

Currency · string

Returned 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 debited funds.

Amount · integer

An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).

NextTransactionFees · object

The fees of the subsequent recurring pay-ins.

Show properties

Currency · string

Returned 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 fees.

Amount · integer

An amount of money in the smallest sub-division of the currency (e.g., EUR 12.60 would be represented as 1260 whereas JPY 12 would be represented as just 12).

Migration · boolean · deprecated

For PayPal recurring registrations, this value is returned false.

PaymentType · string

Returned values: CARD_DIRECT, PAYPAL

Default value: CARD_DIRECT

The type of recurring pay-in registration (which must correspond to the pay-ins requested against it).

400 - One live PayPal registration allowed per user

{
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Id": "be73db6f-f78e-4e71-9602-11633626dc9a",
    "Date": 1731941788,
    "errors": {
        "AuthorId": "RecurringPayInRegistration already exists for given AuthorId=user_m_01JCQYRAFZQMN5TD4X5Z3JFZT0 and PaymentType=PAYPAL"
    }
}

200

{
    "Id": "recpayinreg_wt_c1fb7e3f-8204-4427-9251-df886fbb4e42",
    "Status": "CREATED",
    "ResultCode": null,
    "ResultMessage": null,
    "CurrentState": {
        "PayinsLinked": 0,
        "CumulatedDebitedAmount": {
            "Currency": "EUR",
            "Amount": 0
        },
        "CumulatedFeesAmount": {
            "Currency": "EUR",
            "Amount": 0
        },
        "LastPayinId": null
    },
    "RecurringType": "CUSTOM",
    "TotalAmount": null,
    "CycleNumber": null,
    "AuthorId": "user_m_01J9KR16BG7EDC8RNEY2M18EXK",
    "CardId": null,
    "CreditedUserId": null,
    "CreditedWalletId": "wlt_m_01J9KR4A7BH8KVE4PG6DTNS817",
    "Billing": {
        "FirstName": "Ofelia",
        "LastName": "Kilback",
        "Address": {
            "AddressLine1": "8151 Sipes Turnpike",
            "AddressLine2": "Garfield Meadows",
            "City": "Paris",
            "Region": "Île-de-France",
            "PostalCode": "75001",
            "Country": "FR"
        }
    },
    "Shipping": {
        "FirstName": "Alex",
        "LastName": "Smith",
        "Address": {
            "AddressLine1": "6 rue de la Cité",
            "AddressLine2": "Appartement 3",
            "City": "Paris",
            "Region": "île-de-france",
            "PostalCode": "75003",
            "Country": "FR"
        }
    },
    "EndDate": null,
    "Frequency": null,
    "FixedNextAmount": false,
    "FractionedPayment": false,
    "FreeCycles": 0,
    "FirstTransactionDebitedFunds": {
        "Currency": "EUR",
        "Amount": 10000
    },
    "FirstTransactionFees": {
        "Currency": "EUR",
        "Amount": 1000
    },
    "NextTransactionDebitedFunds": null,
    "NextTransactionFees": null,
    "Migration": false,
    "PaymentType": "PAYPAL"
}

REST

{
    "AuthorId": "user_m_01J9KR16BG7EDC8RNEY2M18EXK",
    "CreditedWalletId": "wlt_m_01J9KR4A7BH8KVE4PG6DTNS817",
    "FirstTransactionDebitedFunds": {
        "Currency": "EUR",
        "Amount": 10000
    },
    "FirstTransactionFees": {
        "Currency": "EUR",
        "Amount": 1000
    },
    "Billing": {
        "FirstName": "Ofelia",
        "LastName": "Kilback",
        "Address": {
            "AddressLine1": "8151 Sipes Turnpike",
            "AddressLine2": "Garfield Meadows",
            "City": "Paris",
            "Region": "Île-de-France",
            "PostalCode": "75001",
            "Country": "FR"
        }
    },
    "Shipping": {
        "FirstName": "Alex",
        "LastName": "Smith",
        "Address": {
            "AddressLine1": "6 rue de la Cité",
            "AddressLine2": "Appartement 3",
            "City": "Paris",
            "Region": "île-de-france",
            "PostalCode": "75003",
            "Country": "FR"
        }
    },
    "PaymentType": "PAYPAL"
}