No momento, esta página não está disponível em português

Update the payment amount

Update the payment amount before making the payment request.

If you want to update the payment amount, for example if the shopper has updated their cart during checkout, you must implement two API calls in addition to /sessions:

/payments: Makes a payment request with the updated amount.
/payments/details: Verifies the payment result in case the payment method requires a redirect or an additional action, such as scanning a QR code or authenticating a payment with 3D Secure.

When creating the configuration object for the AdyenCheckout instance, you need to create event handlers for these API calls.

Before you begin

This page assumes you've already built a Drop-in integration.

Step 1: Create event handlers

When creating a configuration object, include:

onSubmit: Called when the shopper selects the Pay button and the payment details are valid.
onAdditionalDetails: Called when the shopper has completed any additional action required by the payment method, for example scanning a QR code or authenticating a payment with 3D Secure.

const configuration = {
  //... other required configuration
  onSubmit: (state, component) => {
     //  Your function calling your server to make a `/payments` request
  },
  onAdditionalDetails: (state, component) => {
     //  Your function calling your server to make a `/payments/details` request
  }
};

https://docs.adyen.com/pt/pt/online-payments/web-drop-in/additional-use-cases/additional-methods-for-sessions-flow/update-payment-amount#-code-adyencheckout-code-configuration

Step 2: Make a payment request

When the shopper selects the Pay button, Drop-in calls the onSubmit event, which contains a state.data. Pass the state.data to your server.
From your server, make a POST /payments request specifying:

Parameter name	Required	Description
`merchantAccount`		Your merchant account name.
`amount`		The `currency` and the updated `value` of the payment (in minor units).
`reference`		Your unique reference for this payment.
`paymentMethod`		The `state.data.paymentMethod` from the `onSubmit` event from your front end.
`browserInfo`		The `state.data.browserInfo` object from the `onSubmit` event. Required for 3D Secure 2.
`returnUrl`		URL to where the shopper should be taken back to after a redirection. The URL can contain a maximum of 1024 characters and should include the protocol: `http://` or `https://`. You can also include your own additional query parameters, for example, shopper ID or order reference number.

Here's an example of how you would make a payment request for 10 EUR:

curl https://checkout-test.adyen.com/v69/payments \
-H "x-API-key: YOUR_API_KEY" \
-H "content-type: application/json" \
-d '{
  "amount":{
    "currency":"EUR",
    "value":1000
  },
  "reference":"YOUR_ORDER_NUMBER",
  "paymentMethod":{hint:paymentMethod field of an object passed from the front end or client app}STATE_DATA{/hint},
  "returnUrl":"https://your-company.com/checkout?shopperOrder=12xy..",
  "merchantAccount":"YOUR_MERCHANT_ACCOUNT"
}'

require 'adyen-ruby-api-library'

# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.env = :test
adyen.api_key = "YOUR_X-API-KEY"

# STATE_DATA is the paymentMethod field of an object passed from the front end or client app, deserialized from JSON to a data structure.
paymentMethod = STATE_DATA

response = adyen.checkout.payments({ 
    :paymentMethod => paymentMethod,
    :amount => {
        :currency => 'EUR',
        :value => 1000
    },
    :reference => 'YOUR_ORDER_NUMBER',
    :returnUrl => 'https://your-company.com/checkout?shopperOrder=12xy..',
    :merchantAccount => 'YOUR_MERCHANT_ACCOUNT'
})

# Check if further action is needed.
if response.body.has_key(:action)
   # Pass the action object to your front end
   # response.body[:action]
else
   # No further action needed, pass the resultCode object to your front end
   # response.body[:resultCode]

// Set your X-API-KEY with the API key from the Customer Area.
String xApiKey = "YOUR_X-API-KEY";
Client client = new Client(xApiKey,Environment.TEST);
Checkout checkout = new Checkout(client);
PaymentsRequest paymentsRequest = new PaymentsRequest();
paymentsRequest.setMerchantAccount("YOUR_MERCHANT_ACCOUNT");
// STATE_DATA is the paymentMethod field of an object passed from the front end or client app, deserialized from JSON to a data structure.
paymentsRequest.setPaymentMethod(STATE_DATA)
Amount amount = new Amount();
amount.setCurrency("EUR");
amount.setValue(1000L);
paymentsRequest.setAmount(amount);
paymentsRequest.setReference("YOUR_ORDER_NUMBER");
paymentsRequest.setReturnUrl("https://your-company.com/checkout?shopperOrder=12xy..");
PaymentsResponse paymentsResponse = checkout.payments(paymentsRequest);

// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setEnvironment(\Adyen\Environment::TEST);
$client->setXApiKey("YOUR_X-API-KEY");
$service = new \Adyen\Service\Checkout($client);

// STATE_DATA is the paymentMethod field of an object passed from the front end or client app, deserialized from JSON to a data structure.
$paymentMethod = STATE_DATA;;

$params = array(
    "paymentMethod" => $paymentMethod,
    "amount" => array(
        "currency" => "EUR",
        "value" => 1000
    ),
    "reference" => "YOUR_ORDER_NUMBER",
    "returnUrl" => "https://your-company.com/checkout?shopperOrder=12xy..",
    "merchantAccount" => "YOUR_MERCHANT_ACCOUNT"
);
$result = $service->payments($params);

// Check if further action is needed
if (array_key_exists("action", $result)){
   // Pass the action object to your front end
   // $result["action"]
}
else {
   // No further action needed, pass the resultCode to your front end
   // $result['resultCode']
}

# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen.Adyen()
adyen.payment.client.platform = "test"
adyen.client.xapikey = 'YOUR_X-API-KEY'

# STATE_DATA is the paymentMethod field of an object passed from the front end or client app, deserialized from JSON to a data structure.
paymentMethod = STATE_DATA

result = adyen.checkout.payments({
    'paymentMethod': paymentMethod,
    'amount': {
        'value': 1000,
        'currency': 'EUR'
    },
    'reference': 'YOUR_ORDER_NUMBER',
    'returnUrl': 'https://your-company.com/checkout?shopperOrder=12xy..',
    'merchantAccount': 'YOUR_MERCHANT_ACCOUNT'
})

# Check if further action is needed
if 'action' in result.message:
   # Pass the action object to your front end
   # result.message['action']
else:
   # No further action needed, pass the resultCode to your front end
   # result.message['resultCode']

// Set your X-API-KEY with the API key from the Customer Area.
string apiKey = "YOUR_X-API-KEY";
var client = new Client (apiKey, Environment.Test);
var checkout = new Checkout(client);
var amount = new Adyen.Model.Checkout.Amount("EUR", 1000);
var paymentsRequest = new Adyen.Model.Checkout.PaymentRequest
{ 
// STATE_DATA is the paymentMethod field of an object passed from the front end or client app, deserialized from JSON to a data structure.
    PaymentMethod = STATE_DATA,
    Amount = amount,
    Reference = "YOUR_ORDER_NUMBER",
    ReturnUrl = @"https://your-company.com/checkout?shopperOrder=12xy..",
};
var paymentResponse = checkout.Payments(paymentsRequest);

const {Client, Config, CheckoutAPI} = require('@adyen/api-library');
const config = new Config();
// Set your X-API-KEY with the API key from the Customer Area.
config.apiKey = '[YOUR_X-API-KEY]';
config.merchantAccount = '[YOUR_MERCHANT_ACCOUNT]';
const client = new Client({ config });
client.setEnvironment("TEST");
const checkout = new CheckoutAPI(client);
checkout.payments({
    merchantAccount: config.merchantAccount,
// STATE_DATA is the paymentMethod field of an object passed from the front end or client app, deserialized from JSON to a data structure.
    paymentMethod: STATE_DATA,
    amount: { currency: "EUR", value: 1000, },
    reference: "YOUR_ORDER_NUMBER",
    returnUrl: "https://your-company.com/checkout?shopperOrder=12xy.."
}).then(res => res);

import (
    "github.com/adyen/adyen-go-api-library/v5/src/checkout"
    "github.com/adyen/adyen-go-api-library/v5/src/common"
    "github.com/adyen/adyen-go-api-library/v5/src/adyen"
)
// Set your X-API-KEY with the API key from the Customer Area.
client := adyen.NewClient(&common.Config{
    Environment: common.TestEnv,
    ApiKey:      "[YOUR_X-API-KEY]",
})
// STATE_DATA is the paymentMethod field of an object passed from the front end or client app, deserialized from JSON to a data structure.
paymentMethod := STATE_DATA
res, httpRes, err := client.Checkout.Payments(&checkout.PaymentRequest{
    PaymentMethod: paymentMethod,
    Amount: checkout.Amount{
        Value:    1000,
        Currency: "EUR",
    },
    Reference: "YOUR_ORDER_NUMBER",
    ReturnUrl: "https://your-company.com/checkout?shopperOrder=12xy..",
    MerchantAccount: "[YOUR_MERCHANT_ACCOUNT]",
})

https://docs.adyen.com/pt/pt/online-payments/web-drop-in/additional-use-cases/additional-methods-for-sessions-flow/update-payment-amount#payments-request-component

If the /payments response does not contain an action object, you can already present the payment result to the shopper.

If the /payments response contains an action object, pass this to your front end. Drop-in will handle the required action, depending on the action.type. You will then need to make one more API call to verify the payment result.

Action types

`action.type`	Description	Next steps
voucher	Drop-in displays the voucher which the shopper uses to complete the payment.	Inform the shopper that you are waiting for the payment.
redirect	Drop-in redirects the shopper to another website or app to complete the payment.	Handle the redirect result when the shopper returns to your website.
qrCode	Drop-in presents the QR code and calls the `onAdditionalDetails` event.	Handle the additional action.
await	Drop-in shows the waiting screen while the shopper completes the payment. Depending on the payment outcome, Drop-in calls the `onAdditionalDetails` or `onError` event.	Handle the additional action.
sdk	Drop-in presents the specific payment method's UI as an overlay and calls the `onAdditionalDetails` event.	Handle the additional action.
threeDS2	The payment qualifies for 3D Secure 2, and will go through the authentication flow. Drop-in performs the authentication flow, and calls the `onAdditionalDetails` event.	Handle the additional action.

Step 3: Verify the payment result

Handling redirect results

After completing a payment that required a redirect, the shopper is redirected back to your returnUrl with an HTTP GET. The returnUrl is appended with a Base64-encoded redirectResult:

GET /?shopperOrder=12xy..&&redirectResult=X6XtfGC3%21Y... HTTP/1.1
Host: www.your-company.com/checkout

From your server, make a POST /payments/details request with the URL-decoded the redirectResult:

curl https://checkout-test.adyen.com/v68/payments/details \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
    "details": {
      "redirectResult": "eyJ0cmFuc1N0YXR1cyI6IlkifQ=="
  }
}'

https://docs.adyen.com/pt/pt/online-payments/web-drop-in/additional-use-cases/additional-methods-for-sessions-flow/redirect-result#-payments-details-request

Then, use the resultCode from the /payments/details response to present the payment result to the shopper.

Handling additional actions

If the shopper performed additional action, Drop-in calls the onAdditionalDetails event.
From your server, make a /payments/details request, and include the state.data from the onAdditionalDetails event:

curl https://checkout-test.adyen.com/v69/payments/details \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{hint:object passed from the front end or client app}STATE_DATA{/hint}'

require 'adyen-ruby-api-library'

# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.env = :test
adyen.api_key = "YOUR_X-API-KEY"

# STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure.
request = STATE_DATA 
response = adyen.checkout.payments.details(request)  

# Check if further action is needed.
if response.body.has_key(:action)
   # Pass the action object to your frontend
   puts response.body[:action]
else
   # No further action needed, pass the resultCode to your frontend
   puts response.body[:resultCode]
end

// Set your X-API-KEY with the API key from the Customer Area.
String xApiKey = "YOUR_X-API-KEY";
Client client = new Client(xApiKey,Environment.TEST);
Checkout checkout = new Checkout(client);
// STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure.
PaymentsDetailsRequest paymentsDetailsRequest = STATE_DATA;
PaymentsResponse paymentsDetailsResponse = checkout.paymentsDetails(paymentsDetailsRequest);

// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setEnvironment(\Adyen\Environment::TEST);
$client->setXApiKey("YOUR_X-API-KEY");
$service = new \Adyen\Service\Checkout($client);

// STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure.
$params = STATE_DATA;
$result = $service->paymentsDetails($params);

// Check if further action is needed
if (array_key_exists("action", $result)){
   // Pass the action object to your frontend.
   // $result["action"]
}
else {
   // No further action needed, pass the resultCode to your front end
   // $result['resultCode']
}

# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen.Adyen()
adyen.payment.client.platform = "test"
adyen.client.xapikey = 'YOUR_X-API-KEY'

# STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure.
request = STATE_DATA
result = adyen.checkout.payments_details(request)

# Check if further action is needed.
if 'action' in result.message:
   # Pass the action object to your front end
   # result.message['action']
else:
   # No further action needed, pass the resultCode to your front end
   # result.message['resultCode']

// Set your X-API-KEY with the API key from the Customer Area.
string apiKey = "YOUR_X-API-KEY";
var client = new Client (apiKey, Environment.Test);
var checkout = new Checkout(client);
// STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure.
var paymentsDetailsRequest = STATE_DATA;
var paymentsDetailsResponse = checkout.PaymentDetails(paymentsDetailsRequest);

const {Client, Config, CheckoutAPI} = require('@adyen/api-library');
const config = new Config();
// Set your X-API-KEY with the API key from the Customer Area.
config.apiKey = '[YOUR_X-API-KEY]';
const client = new Client({ config });
client.setEnvironment("TEST");
const checkout = new CheckoutAPI(client);
// STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure.
checkout.paymentsDetails(STATE_DATA).then(res => res);

import (
    "github.com/adyen/adyen-go-api-library/v5/src/checkout"
    "github.com/adyen/adyen-go-api-library/v5/src/common"
    "github.com/adyen/adyen-go-api-library/v5/src/adyen"
)
// Set your X-API-KEY with the API key from the Customer Area.
client := adyen.NewClient(&common.Config{
    Environment: common.TestEnv,
    ApiKey:      "[YOUR_X-API-KEY]",
})
// STATE_DATA is an object passed from the front end or client app, deserialized from JSON to a data structure.
req := STATE_DATA;
res, httpRes, err := client.Checkout.PaymentsDetails(&req)

https://docs.adyen.com/pt/pt/online-payments/web-drop-in/additional-use-cases/additional-methods-for-sessions-flow/update-payment-amount#details-request-component

Then, use the resultCode from the /payments/details response to present the payment result to the shopper.

Step 4: Present the payment result

After the shopper completes the payment, use the resultCode to inform the shopper of the payment status.

resultCode	Description	Action to take
Authorised	The payment was successful.	Inform the shopper that the payment was successful.
Error	Inform the shopper that there was an error processing their payment.	You'll receive a `refusalReason` in the same response, indicating the cause of the error.
Pending	The shopper has completed the payment but the final result is not yet known.	Inform the shopper that you've received their order, and are waiting for the payment to be completed.
PresentToShopper	Present the voucher or the QR code to the shopper.	For a voucher payment method, inform the shopper that you are waiting for their payment. For a qrCode payment method, wait for the AUTHORISATION notification before presenting the payment result to the shopper.
Refused	The payment was refused.	Inform the shopper that the payment was refused. Ask the shopper to try the payment again using a different payment method or card.
Received	For some payment methods, it can take some time before the final status of the payment is known.	Inform the shopper that you've received their order, and are waiting for the payment to clear.

For other possible resultCode values and recommended messages that you can present to your shopper, see Result codes.
Alternatively, you can use the dropin.setStatus to show a customized message. For example:

  // Show a success message
  dropin.setStatus('success');
  dropin.setStatus('success', { message: 'Payment successful!' });

  // Show an error message
  dropin.setStatus('error');
  dropin.setStatus('error', { message: 'Something went wrong.'});

  // Set a loading state
  dropin.setStatus('loading'); // start the loading state
  dropin.setStatus('ready'); // set back to the initial state