Migrate from the legacy API

If you are currently using the legacy Younited Pay API, this guide will help you to migrate to the new API.

General behavioral differences

The new API introduces the concept of Payment. A payment can be of different types, such as Personal Loans Payments. Legacy API use the notion of Contract.
The new API does not require the merchant to confirm the payment. Once a payment is accepted, merchant can only execute or cancel it.
The new API does not expose the customer's personal data.
The new API use Payment Id to identify a payment. The Payment Id is unique and is only generated by the new Younited Pay API. You cannot use the legacy Contract Reference to identify a payment.
Webhooks are now used to notify the merchant of payment and refunds changes. The merchant must provide a URL to receive these notifications.

Discontinued functionality

`Load a contract by reference` endpoint is now replaced by the `Get Payment` endpoint. The new endpoint does not expose the customer's personal data.
`Confirm a contract` endpoint no longer exists. The new API does not require the merchant to confirm the payment.
`Get Younited Pay available maturities` endpoint no longer exists.

Attention point

The contract reference of a legacy contract cannot be used directly on the new API, but you can generate a PaymentId thanks to the GET api/1.0/Contract/{contractReference}/payment-id on the legacy API.
You can use the new API to operate legacy contract with the PaymentId.
Legacy contract will continue to trigger legacy webhook notification with legacy format.
Newly created payment will only trigger notification with new format.

Migration path

Update your codebase to identify the version of the API used for a specific contract. You can rely on the 'ContractReference' / 'PaymentId' format to do so.
Call the Get payment ID for legacy contract GET specific-use-cases/legacy-contracts/{reference}/payment-id when needed for legacy contract to get the associated PaymentId.
Update your code to manage the new webhook format but DO NOT remove legacy webhook endpoint as those will still be needed to operate legacy contract.
Update your code to call the new Payment API following this migration guide.

Get Younited Offer

Attention point

You now need to provide maturity parameter.

Legacy API

BestPrice, Get Younited Pay eligible offers, per maturities

Request

POST/api/1.0/BestPrices

Query parameters: -

Body:

{
    "borrowedAmount": 2500,
    "shopCode": "Shop"
}

Response

200

[
   {
       "requestedAmount": 2500,
       "annualPercentageRate": 0.099,
       "annualDebitRate": 0.094,
       "monthlyInstallmentAmount": 274.75,
       "creditTotalAmount": 2500,
       "creditAmountToFund": 2500,
       "maturityInMonths": 10,
       "interestsTotalAmount": 247.5
   }
]

New API

Personal Loans, Get personal loan offers

Request

GET/personal-loans/offers

Query parameters:

Amount: The amount for the personal loan payment offers.
ShopCode: Merchant shop code.
Maturity.List: A list of maturity periods separated by a comma (e.g., "12,24,36"). You can either fill the List parameter or Range.Min, Range.Max and Range.Step.
Maturity.Range.Min: The minimum value for the maturity range.
Maturity.Range.Step: The step value for the maturity range.
Maturity.Range.Max: The maximum value for the maturity range.

Body:

Response

200

[
  {
    "requestedAmount": 1115.99,
    "characteristics": {
      "amount": 1115.99,
      "maturityInMonths": 12,
      "interestRate": 0.05,
      "downPaymentAmount": 0, 
      "feesAmount": 0
    },
    "details": {
      "annualPercentageRate": 0.05,
      "monthlyInstallmentAmount": 100.14,
      "interestsAmount": 12.57,
      "totalDueAmount": 1200.57
    }
  }
]

Create a new contract

Attention point

onApplicationSucceededRedirectUrl and onApplicationFailedRedirectUrl are now merged into one single customerRedirectUrl.
onGrantedWebhookUrl, onCanceledWebhookUrl, onWithdrawnWebhookUrl and onActivateWebhookUrl are now merged into one single webhookNotificationUrl.
ShopCode is now mandatory.

The return object now contains a paymentId and no longer a contractReference.

Legacy API

Contract, Initialize a new contract request

Request

POST/api/1.0/Contract

Query parameters: -

Body:

{
  "requestedMaturity": 10,
  "personalInformation": {
    "firstName": "Dale",
    "lastName": "Stephens",
    "genderCode": "MALE",
    "emailAddress": "customerEmailAddress@somemail.com",
    "cellPhoneNumber": "+33611223344",
    "birthDate": "1990-02-20T00:00:00",
    "address": {
      "streetNumber": "21",
      "streetName": "rue de chateaudun",
      "additionalAddress": "not necessary",
      "city": "Paris",
      "postalCode": "75009",
      "countryCode": "FR"
    }
  },
  "basket": {
    "basketAmount": 2500,
    "items": [
      {
        "itemName": "Expensive item",
        "quantity": 1,
        "unitPrice": 2500
      }
    ]
  },
  "merchantUrls": {
    "onGrantedWebhookUrl": "https://www.notifyMeHere.com/granted",
    "onCanceledWebhookUrl": "https://www.notifyMeHere.com/canceled",
    "onWithdrawnWebhookUrl": "https://www.notifyMeHere.com/withdrawn",
    "onApplicationSucceededRedirectUrl": "https://www.redirectMeHere.com/success",
    "onApplicationFailedRedirectUrl": "https://www.redirectMeHere.com/failure",
    "onActivateWebhookUrl": "https://www.notifyMeHere.com/activate"
  },
  "merchantOrderContext": {
    "channel": "ONLINE",
    "shopCode": "ONLINE",
    "agentEmailAddress": "merchantEmailAddress@somemail.com",
    "merchantReference": "merchantInternalReference"
  }
}

Response

200

{
"contractReference": "CFR20211231CP4NYRZ",
"redirectUrl": "https://clafr.younited-pay.com/start?requestId=xxxxxxxxxxxxx"
}

New API

Payment, Create Personal Loan payment

Request

POST/payments/personal-loan

Query parameters: -

Body:

{
  "loanRequest": {
    "requestedAmount": 1015.99,
    "requestedMaturityInMonths": 12
  },
  "basketDescription": {
    "items": [
      {
        "name": "Cellphone",
        "quantity": 1,
        "unitPrice": 1115.99
      },
      {
        "name": "Membership Discount",
        "quantity": 1,
        "unitPrice": -100
      }
    ]
  },
  "customerInformation": {
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "customer@email.com",
    "mobilePhoneNumber": null,
    "birthDate": null,
    "postalAddress": null
  },
  "merchantContext": {
    "shopCode": "SHOP-123456",
    "merchantReference": "MERCHANT-123456",
    "salesClerkContactEmailAddress": null
  },
  "technicalInformation": {
    "webhookNotificationUrl": "https://merchant.com/webhook",
    "apiVersion": "2024-01-01"
  },
  "customExperience": {
    "customerRedirectUrl":"https://www.redirectMeHere.com/"
  },
  "riskInsights": null
}

Response

200

{
  "paymentId": "YPAY_49f3b63d-7521-44a4-88b8-0575059e5cb7",
  "paymentLink": "https://payment.younited.com?token=xxxxxxxxxxxxx"
}

Get Contract

Attention point

offer and basket and personalInformation are no longer returned.

Legacy API

Contract, Load a contract by reference

Request

GET/api/1.0/Contract/{contractReference}

Query parameters:

contractReference: the contract reference

Body:

Response

200

{
  "reference": "CFR20211231CP4NYRZ",
  "status": "GRANTED",
  "applicationSucceeded": true,
  "offer": {
    "requestedAmount": 2500,
    "annualPercentageRate": 0.099,
    "annualDebitRate": 0.094,
    "monthlyInstallmentAmount": 274.75,
    "creditTotalAmount": 2500,
    "creditAmountToFund": 2500,
    "maturityInMonths": 10,
    "interestsTotalAmount": 247.5
  },
  "basket": {
    "basketAmount": 2500,
    "items": [
      {
        "itemName": "Expensive item",
        "quantity": 1,
        "unitPrice": 2500
      }
    ]
  },
  "merchantOrderContext": {
    "channel": "ONLINE",
    "shopCode": "ONLINE",
    "agentEmailAddress": "agentEmailAddress@fromInitializePayload.com",
    "merchantReference": "merchantReferenceFromInitializePayload"
  },
  "personalInformation": {
    "firstName": "Kevin",
    "lastName": "Last",
    "genderCode": "MALE",
    "emailAddress": "mail@mail.com",
    "cellPhoneNumber": "0605040302",
    "birthDate": "2000-07-01T00:00:00",
    "address": {
      "streetNumber": "1",
      "streetName": "rue de paris",
      "city": "Paris",
      "postalCode": "75020",
      "countryCode": "FR"
    }
  }
}

New API

Payment, Get Payment

Request

GET/payments/{paymentId}

Query parameters:

paymentId: the payment Identifier

Body:

Response

200

{
  "id": "YPAY_3de5d1dd-93dd-4ae9-8c76-434900e24cbf",
  "type": "PersonalLoan",
  "status": "Approved",
  "amount": 1000,
  "personalLoanPaymentDetails": {
    "loanReference": "CFR20211010XXXXXX"
  },
  "createdAt": "2021-10-10T11:11:12Z",
  "executableUntil": null,
  "refundedAmount": 50,
  "isRefunded": null,
  "executedAt": null,
  "refundableUntil": null
}

Legacy Contract status and equivalent Payment status:

Legacy status	New API status	Note
INITIALIZED	Initialized
REJECTED	Failed
CANCELED	Cancelled
GRANTED	Accepted
CONFIRMED	-	This notion no longer exists. A legacy 'Confirmed' contract will be in 'Accepted' status on the new API.
FINANCED	Executed
WITHDRAWN	Executed	A payment status will remained `Executed` when fully refunded. You can get the refunded amount with the `GetPayment` endpoint.

Contract actions

Attention point

Confirm action is no longer needed / supported.

Cancel

Legacy API

Contract, Cancel a contract

Request

DELETE/api/1.0/Contract/{contractReference}

Query parameters:

contractReference: the contract reference

Body:

Response

204

New API

Payment, Cancel Payment

Request

POST/payments/{paymentId}/cancel

Query parameters:

paymentId: the payment identifier

Body:

Response

204

Activate

Legacy API

Contract, Activate a contract

Request

POST/api/1.0/Contract/{contractReference}/activate

Query parameters:

contractReference: the contract reference

Body:

Response

204

New API

Payment, Execute Payment

Request

POST/payments/{paymentId}/execute

Query parameters:

paymentId: the payment identifier

Body:

Response

204

Withdraw

Attention point

Withdraw no longer has an impact on the payment status. You can identify a fully refunded payment by checking the 'IsRefunded' property on the GetPayment endpoint.
You now have to provide a unique string that identifies this refund request. This key must be unique for every refund request made on a payment.

Legacy API

Contract, Activate a contract

Request

PATCH/api/1.0/Contract/{contractReference}/withdraw

Query parameters:

contractReference: the contract reference

Body:

{
  "amount": 0
}

Response

204

New API

Refunds, Refund payment

Request

POST/refunds

Query parameters: -

Body:

{
    "paymentId": "YPAY_0197613d-c0fd-4237-968a-19e25467d963",
    "idempotencyKey": "REFUND_ID_123456",
    "amount": 1400.56
}

Response

204

Webhook notifications

Attention point

The new API now use only one webhookNotificationUrl where all the payment related notification are send.
There is a new type property on the payload to filter the event.
To monitor a withdraw on a credit application you now need to listen to 'refund.created' event.
Signature verification mechanism does not changes between legacy and new API.

Legacy API

Webhook

POSTonCanceledWebhookUrl

POSTonGrantedWebhookUrl

POSTonActivateWebhookUrl

Headers parameters:

X-YC-Signature-256: the signature value.
X-YC-DateTime: the request execution utc date value.

Body:

{
    "contractReference": "string",
    "merchantReference": "string",
    "merchantOrderId": "string",
    "eventDate": "2019-08-24T14:15:22Z"
}

New API

Webhook

POSTwebhookNotificationUrl

Headers parameters:

x-younited-hmacsha256-signature: An HMAC-SHA256 signature used to validate the event authenticity.
x-younited-version: The version of the API used to create the event notification.
x-younited-retry-attempts: The number of times Younited has resent a notification for the given event.
x-younited-datetime: The notification sent datetime used to computed the signature..

Body:

{
    "type": "payment.updated",
    "notificationId": "5ef9f8e6-2bc0-456b-82d7-f028be989b33",
    "data": {
        "type": "payment",
        "paymentId": "YPAY_e99376c0-4d41-4155-b773-5f61b68bef6d",
        "status": "Executed",
        "updatedAt": "2024-12-26T18:39:42.9927602"
    },
    "createdAt": "2024-12-26T18:39:47.3428149Z"
}

Legacy API

Webhook

POSTonWithdrawnWebhookUrl

Headers parameters:

X-YC-Signature-256: the signature value.
X-YC-DateTime: the request execution utc date value.

Payload:

{
    "contractReference": "string",
    "merchantReference": "string",
    "merchantOrderId": "string",
    "eventDate": "2019-08-24T14:15:22Z"
}

New API

Webhook

POSTwebhookNotificationUrl

Headers parameters:

x-younited-hmacsha256-signature: An HMAC-SHA256 signature used to validate the event authenticity.
x-younited-version: The version of the API used to create the event notification.
x-younited-retry-attempts: The number of times Younited has resent a notification for the given event.
x-younited-datetime: The notification sent datetime used to computed the signature..

Payload:

{
    "type": "refund.created",
    "notificationId": "5ef9f8e6-2bc0-456b-82d7-f028be989b33",
    "data": {
        "type": "refund", 
        "paymentId": "YPAY_e99376c0-4d41-4155-b773-5f61b68bef6d", 
        "reference": "CFR20241226RXG5R92_12345", 
        "amount": 1500, 
        "createdAt": "2024-12-26T18:39:54.7174841"
    },
    "createdAt": "2024-12-26T18:39:47.3428149Z"
}