Skip to content

API Specification for Payment

Jump to bottom
Reyzis2021 edited this page Jul 29, 2023 · 3 revisions

Specification for Payment API of Online-Store

POST .../api/v1/payment

Summary:
This endpoint responsible for payment creation and processing.

Description:
Processes the payment securely using Stripe API. The payment information will be sent using SSL encryption.

Request:

Parameter In Type Required Description
paymentMethodId body string true This id obtained from the Stripe Initiate Payment API.
totalPrice body decimal true Total payment amount for cart products.
paymentMethodId body string true Сurrency in which the order is paid.

Request Example:

POST .../api/v1/payment

{
  "paymentMethodId": "pm_1NYmg2LyLLVX7AfSlEKO7SoP",
  "priceDetails" : {
    "totalPrice" : 50.0,
    "currency" : "usd"
  }
}

Responses:

200 OK

Parameter Type Required Description
paymentToken string true Secret token generated by a payment intent for the frontend.
paymentId long true Payment identifier.
totalPrice decimal true Total payment amount for cart products.
paymentIntentId string true Payment intent Stripe API identifier.
currency string true Сurrency in which the order is paid.
status string true Payment status.
description string true Payment description.

Response Example:

{
  "paymentToken": "pi_3NZ6zULyLLVX7AfS1s9TnUB2_secret_RoPHXvxHo1GjdaQIRX7U9kwW2",
  "paymentDetailsDto": {
    "paymentId": 1,
    "totalPrice": 50.0,
    "paymentIntentId": "pi_3NZ6zULyLLVX7AfS1s9TnUB2",
    "currency": "usd",
    "status": "PAYMENT_IS_SUCCEEDED",
    "description": "Payment is succeeded"
  }
}

400 Bad Request

If the client sends an invalid request, a 400 Bad Request should be returned.

Parameter Type Required Description
message string true Error message indicating the reason of the failure.
description string true Error description.
timestamp timestamp true Indicating the failure time.

Response Examples:

{
  "message": "Cannot process payment intent with payment method Id: pm_1NZ8ENLyLLVX7AfSde3giX95",
  "description": "Failed to Process a Payment Intent",
  "timestamp": "2023-07-29T08:06:53.679093300Z"
}

GET .../api/v1/payment/{paymentId}

Summary:
Returns payment details.

Description:
Retrieves the details of a particular payment transaction. If the payment was successful or failed, the response will include relevant payments details. If there was an error in the payment processing or currency conversion, detailed information on what went wrong will be provided.

Request:

Parameter In Type Required Description
paymentId url long true Payment identifier.

Request Example:

POST .../api/v1/payment/1

Responses:

200 OK

Parameter Type Required Description
paymentId long true Payment identifier.
totalPrice decimal true Total payment amount for cart products.
paymentIntentId string true Payment intent Stripe API identifier.
currency string true Сurrency in which the order is paid.
status string true Payment status.
description string true Payment description.

Response Example:

{
  "paymentId": 1,
  "totalPrice": 50.0,
  "paymentIntentId": "pi_3NZ6zULyLLVX7AfS1s9TnUB2",
  "currency": "usd",
  "status": "PAYMENT_IS_SUCCEEDED",
  "description": "Payment is succeeded"
}

400 Bad Request

If the client sends an invalid request, a 400 Bad Request should be returned.

Parameter Type Required Description
message string true Error message indicating the reason of the failure.
description string true Error description.
timestamp timestamp true Indicating the failure time.

Response Examples:

{
  "message": "Payment with id 8 not found.",
  "description": "Failed To Find a Payment",
  "time": "2023-07-29T08:22:50.822318200Z"
}

POST .../api/v1/payment/method

Summary:
Returns payment method token.

Description:
Method return payment id that will be used to create the payment intent.

Request:

Parameter In Type Required Description
cardNumber body string true Customer card number.
expMonth body long true Customer card expire month.
expYear body long true Customer card expire year.
cvc body string true Customer card CVC.

Request Example:

POST .../api/v1/payment/method

{
  "cardNumber" : "4242424242424242",
  "expMonth" : 8,
  "expYear" : 2024,
  "cvc" : "314"
}

Responses:

200 OK

Parameter Type Required Description
paymentMethodId string true Payment method identifier.

Response Example:

{
  "paymentMethodId": "pm_1NZ8ENLyLLVX7AfSde3giX95"
}

POST .../api/v1/payment/method

Summary:
Returns payment method token.

Description:
Method return payment id that will be used to create the payment intent.

Request:

Parameter In Type Required Description
cardNumber body string true Customer card number.
expMonth body long true Customer card expire month.
expYear body long true Customer card expire year.
cvc body string true Customer card CVC.

Request Example:

POST .../api/v1/payment/method

{
  "cardNumber" : "4242424242424242",
  "expMonth" : 8,
  "expYear" : 2024,
  "cvc" : "314"
}

Responses:

200 OK

Parameter Type Required Description
paymentMethodId string true Payment method identifier.

Response Example:

{
  "paymentMethodId": "pm_1NZ8ENLyLLVX7AfSde3giX95"
}

400 Bad Request

If the client sends an invalid request, a 400 Bad Request should be returned.

Parameter Type Required Description
message string true Error message indicating the reason of the failure.
description string true Error description.
timestamp timestamp true Indicating the failure time.

Response Examples:

{
  "message": "Cannot process payment method with type: Card",
  "description": "Failed to Process a Payment Method",
  "time": "2023-07-29T08:22:50.822318200Z"
}

POST .../api/v1/payment/event

Summary:
Handling webhook payment intent event.

Description:
Method handling webhook payment intent event and process it according to the scenario. Method returns nothing.

Request:

Parameter In Type Required Description
paymentIntentPayload body string true This is payload of payment intent event
stripeSignatureHeader body long true This is stripe signature

Request Example:

POST .../api/v1/payment/event

{
  "paymentIntentPayload" : "{id: evt_3NZ9J6LyLLVX7AfS12C73Kp,object: event,api_version: 2022-11-15,created:....",
  "stripeSignatureHeader": "t=1690622369,v1=372a0163d87e3b26448d4203768962162a03fb5a2ca5b3316c733a0cd3f167f4,v0=0c15d86b2f8fe2f24e01c4f96178b063b04ddb2fb57120f790b721cd9009daed"
}

400 Bad Request

If the client sends an invalid request, a 400 Bad Request should be returned.

Parameter Type Required Description
message string true Error message indicating the reason of the failure.
description string true Error description.
timestamp timestamp true Indicating the failure time.

Response Examples:

{
  "message": "Payment event with stripe signature v1=372a0163d87e3b26448d4203768962162a03fb5a2ca5b3316c733a0cd3f167f4, can't be processed.",
  "description": "Failed to Parse a Payment Event",
  "time": "2023-07-29T08:22:50.822318200Z"
}

API for Java client

public interface PaymentApi {

    /**
     * This method allows to create a payment object
     *
     * @param createPaymentDto the request dto to create a payment object
     * @return PaymentDetailsWithTokenDto combines payment details and a payment token for payment processing on the front end side
     * */
    PaymentDetailsWithTokenDto createPayment(final CreatePaymentDto createPaymentDto);

    /**
     * This method allows to create a payment method object
     *
     * @param createPaymentMethodDto the request dto to create a payment method object
     * @return String payment method identifier, for secure method transfer using the Stripe API
     * */
    String createPaymentMethod(final CreatePaymentMethodDto createPaymentMethodDto);

    /**
     * This method allows to create a payment method object
     *
     * @param paymentId the payment identifier to search payment details
     * @return PaymentDetailsDto these are payment details
     * */
    PaymentDetailsDto getPaymentDetails(final Long paymentId);

    /**
     * This method allows to create a payment method object
     *
     * @param paymentIntentPayload this param it is a string describing of the payment intent event type.
     * @param stripeSignatureHeader this param it is a string describing of the stripe signature, which provide safe work with Stripe API webhooks mechanism
     * */
    void processPaymentEvent(final String paymentIntentPayload, final String stripeSignatureHeader);

}

    public record CreatePaymentDto(

            @NotBlank(message = "PaymentMethodId is the mandatory attribute")
            String paymentMethodId,

            @NotNull(message = "PriceDetails is the mandatory attribute")
            PriceDetailsDto priceDetails
    ) {
    }

    public record CreatePaymentMethodDto (

            @NotBlank(message = "CardNumber is the mandatory attribute")
            String cardNumber,

            @NotNull(message = "ExpMonth is the mandatory attribute")
            Long expMonth,

            @NotNull(message = "ExpYear is the mandatory attribute")
            Long expYear,

            @NotNull(message = "Cvc is the mandatory attribute")
            String cvc
    ) {
    }

    @Builder
    public record PaymentDetailsDto(
            Long paymentId,
            BigDecimal totalPrice,
            String paymentIntentId,
            String currency,
            PaymentStatus status,
            String description
    ) {
    }

    @Builder
    public record PaymentDetailsWithTokenDto(
            String paymentToken,
            PaymentDetailsDto paymentDetailsDto
    ) {
    }

    public record PriceDetailsDto(

            @NotNull(message = "Total price is mandatory attribute")
            BigDecimal totalPrice,

            @NotBlank(message = "Currency is mandatory attribute")
            @Size(min = 3, max = 3, message = "Currency value must be only 3 characters long")
             String currency
    ) {
    }
Clone this wiki locally