Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 6 Next »

This chapter will describe the flow of performing either a one-time or recurring payment.

Step 1: Request a payment

The first step is that the merchant sends a POST request to Globadyme.

Expected is a JSON body containing the transaction data and the merchant password, provided by Globadyme. 

Url: https://sandbox.globadyme.com/api/globadymeGateway/transaction/requestPayment

Request example for one-time payment:

{
    "transaction" : { 
        "merchantId": "7699cab7-2dfa-4981-9c90-0d0c93c801ac ",	// Merchant UUID
        "amount": "10.00", 			    // Amount, containing cents 
        "currency": "EUR", 			    // ISO 4217 currency code 
        "country": "NL", 			    // ISO 3166-1 alpha-2 country code 
        "description": "TestPayment", 	            // Transaction description
        "accountHolderName" : "Test account holder" // Account holder name
    },
    "password": "MerchantTestPassword" // Merchant API password, provided by Globadyme
}

The following transaction fields are mandatory for all payments:

  • merchantId

  • amount

  • currency

  • country

  • description (provided by the merchant. NB: this description will show up on bank statements and such)

  • accountHolderName (provided by merchant)

The password field is also mandatory and is provided by Globadyme as your API Password.

The following fields are mandatory for Klarna payments:

  • klarnaSpec: In order to be able to process Klarna payments, this field and its sub elements must be filled.

    • billingAddress: containing the following mandatory sub elements:

      • attention: the attention string, for example the department of the addressee

      • email: Customer e-mailaddress

      • city

      • familyName

      • givenName

      • phoneNumber

      • postalCode

      • region

      • streetAddress1

      • streetAddress2 (if applicable)

      • title

    • orderItems: A list of the items being ordered. Note that the sum of the totalAmounts must add up to the total transaction amount. If not, the payment request wil be rejected. Has the following mandatory sub elements:

      • name

      • quantity

      • totalAmount: The total amount in cents

      • unitPrice: unit price in cents

Example of a Klarna payment request:

{
    "transaction": {
        "merchantId": "7699cab7-2dfa-4981-9c90-0d0c93c801ac",
        "amount": "250.00",
        "currency": "EUR",
        "country": "NL",
        "description": "KlarnaTestTransaction",
        "accountHolderName" : "Test account holder" // Account holder name
        "klarnaSpec": {
            "billingAddress": {
                "attention": "Attn",
                "email": "test@test.com",
                "city": "Amsterdam",
                "familyName": "Janssen",
                "givenName": "Piet",
                "phoneNumber": "+31612345678",
                "postalCode": "1021AA",
                "region": "Noord-Holland",
                "streetAddress1": "Kasteelstraat 123",
                "streetAddress2": "Amsterdam",
                "title": "Hr."
            },
            "orderItems": [{
                    "name": "Waterbottle",
                    "quantity": 2,
                    "totalAmount": 10000,
                    "unitPrice": 5000
                }, {
                    "name": "Macbook",
                    "quantity": 1,
                    "totalAmount": 15000,
                    "unitPrice": 15000
                }
            ]
        }
    },
    "password" : " MerchantTestPassword"
}

The following fields are mandatory for recurring payments:

  • transactionRecurrenceType. This will default to ONETIME if not present. For recurring payments, this field needs to be present and filled with FIRST. This will then be the first in a series of recurring payments, also serving as the mandate for future payments. Scheduling and execution of subsequent recurrences are handled by Globadyme according to parameters set in the next field.

  • recurrence. Its sub elements are (all mandatory):

    • recurrenceStatus (must be ACTIVE)

    • startDate: the date at which the first recurrence is to take place. This is NOT the date where the initial transaction will take place, but when the first recurrence will take place.

    • recurrenceAmount: The amount to be paid on each recurrence. This amount does not have to be the same as the initial transaction amount.

    • recurrenceFrequency: The frequency at which recurrences should be executed. The frequency will come into play after the startDate. For example, when the startDate is 2023-08-01 and the recurrenceFrequence==MONTHLY, the first recurrence will be executed on 2023-08-01, the second on 2023-09-01, etc. Possible values:

      • DAILY

      • WEEKLY

      • MONTHLY

      • QUARTERLY

      • YEARLY

Example of recurring payment request:

{
    "transaction": {
        "merchantId": "7699cab7-2dfa-4981-9c90-0d0c93c801ac",
        "amount": "250.00",
        "country": "NL",
        "currency": "EUR",
        "description": "Test recurring transaction",
        "accountHolderName" : "Test account holder", // Account holder name
        "transactionRecurrenceType": "FIRST",
        "recurrence": {
                "recurrenceStatus": "ACTIVE",
                "startDate": "2023-08-31",
                "recurrenceAmount": "90.00",
                "recurrenceFrequency": "MONTHLY"
        }
    }, 
    "password" : "MerchantApiPassword" 
}

The following fields are mandatory for SEPA payments:

  • sepaSpec: Container for the SEPA properties

    • emailAddress: the buyer's e-mailaddress

    • postalAddress: the buyer's postal address

    • iban: The buyer's IBAN 

Example of a SEPA payment request:

{
    "transaction": {
        "merchantId": "7699cab7-2dfa-4981-9c90-0d0c93c801ac",
        "amount": "368.00",
        "currency": "EUR",
        "country": "NL",
        "description": "TestSEPASpecTST",
        "accountHolderName": "Test klant SEPA",
        "sepaSpec": {
            "emailAddress": "klant@harry.com",
            "postalAddress": "klantstraat 14 5920JQ Klantstad",
            "iban": "ES9121000418450200051332"
        }
    },
    "password" : "MerchantTestPassword"
}

Step 2: Receive a response

After sending your request, you will receive a response containing a redirect url. 

The response also contains a requestId which is unique for this transaction request. We'll see this ID again in the Callback chapter.

Response example for any (one-time or recurring) transaction:

{
    "message": "OK",
    "details": {
        "requestId": "852f0c72-0024-4070-9ac7-563eeb4755f6" // Unique ID for this request
        "redirectUrl": "https://dev.globadyme.com/pay?data=0f628205c22995c7eda38b96b336df05421b3464055fc756cb8a61ce2d052bf35f80a0d43fc6541152a58644b2952927b86e5333b4d0d94c8a30d5b3c17b3fd68af5246aa0e37b261375646d519c2539d4f6fd01254474ab66221835a9604ad27c7d8d3a31d601c3937e322b0d5c87482229e008ccd28dce88fd98cbfba4014a8c6a999698628ca08b8fc8988696cf08fac22c61a431c9d0384255b3e7ac3ffdc264446bb45ac5dbad38411a93ce2d3ae11f2a0b078e6dea72c662152d5e862e5e59e26ce32a4f51448c3bec26d8b211706cbc83e70fa87536ced4cacdb2f844b5651e3d6ce5aa7dbb57b556b1cafda0f2f9fd9742106d324a857e577dd47bf50031653f0554e0e3226b46783544734ed3c5136f03f6ce6ac9b39b126395671169c0342c7807e0332342d090b58890be9a872be5d7b23b6b8f0bd1d1ac600330700f247a2cb2b77e345549fe4d743b3c02ee116640e9cc338fb9023b21f19b69bc2515ed3bf498d003a7c495d2fb520b864e580242ef94a294db6f431015bf5c644e23f09e94718635eafccfbd7c946654d0ba9560fe7d57dec1b2209d713c3a6767a76ede2ff6d2b51b17d9d7073c078419599e6675815776b9285af5e661b80f6402bb2c85a9edadae2817bb50b9f069610e0376b16b88a2d1f9cef2820e5be7b2e7deb52d2ab85d10f5ca526cf7feb20408b74481ef7ec579af79092e4afdd66dbe63e906eadf316fc5a193f52af7db22532e793ba5c6e2e35e1a4dbf8e2a6c9aa65cfc8c4e8c8617a89d24dc93c2050cf2fcc5f2c24eff778c3a3ff83183eb4117a2ce55f0f09bf0282c3d328f423efb4c30cebcfaf9d25ebfbf55341d099561aac5a1bc1d9d33d40457f3b5cb55c5b53c0fc1dacc47e4f4ec5a64c282d27664375d0ed30986ebcb77532be586c14cdca31ffc9dfffbc5fa1d76d0de0524aff98db0040b58802371ac48632aec8a160ff023bbda12c36ca1d2b85dbde0513884f6f233c73c5dc32bb4216ffe9c5e93e12c0390a1b9ba1dbf81a9bb251c79903a09781fb1bfa5e821e5ab8af980e01ba2629fb957299517cab38ce42888f90d72e8cc8a96d70b96c42446e325c66734bd77e62ddc5c0d73e1551cd1dd5cdccea169fc21e23c5a2ba674de86ba4c8a573933b224bb538141e06d639b6cf0073894104315c4b0f581e191bda8ed5ed3ae2779db24c3a49837b02f2652bd317f3cb28040eb0885acd4edb1ac4240e56dfdbddd10fc2edf9946f11a819369f665de2753bab777583e113f7f8c847e34be6b0d3a6cf103f2d01cb90a583589b0d82b7aa3d6210d9673dca12166bf507d175dd15d2ef06699f9009ec2478ee73a49d3864ec5c9281068f77978594755ad84d347f892aa2099c91633e3cf328965f67e17470d39daa4b35ab13983ee6f0486f9372b7a79329595640f9ef6196b211c5f3ebb7f887d58cb69a6c20db44971832a936a4c0dbfeb37dfed7b6336adf1d3529f140306316a5eb12b9539edc16d3410800197ae196ef02e6150d47d1adc11a0c3d1f37d6ed5b3db19be19e557ad92da8286249536ed6116178ae0a08dedec6c7ce76f7d52c2eacb4a0c473d4387ad23784912a61d7948d8a9ecf5ff32e040ae889a6cd49884aeea545c12fb7752a2c05ddb7d42c4b23b59d2062d31a1235f8bb3b9b5426d484403b73a8a63be591292d80151ec2ad345072d153d6e0b11f6689b8472c4dad421e06502392bea0fbf66fb8d93613d20104ee8d8c2f7865a4a6021aa315e25657fd9aaedcd8429fae352542231bfafedfbdd83b8aad72ecfa40703b27306e4956eb6f96b7473fab254e6d8e705add9fa2910a2e673055dd716f0d9ccce060cf15e5022864565ec36bcec430f06ea70f8fe3eeafeb301517a9e4af367794803ea2d0efe8ddb7ab24a36d55d07c3b9e77a38599c6b03f84ceb830eb1fa1944f66efe9b24179c53e821692ec0e2ced394f8971ccdd294e9a9fb379e978fd0b06afc928dd7da8149060cadb0ebd38d936eb019745c00d1f0e7a4d6879eb7ce1e0734e1bab61eb733fb184e9fde20c140096f068605de0e5b3ea112e46d0cee8f84b159884d4169f3b702f12bf832ea415db0abf68a72917b3ad0e0c7c17d788f3547e896add17f442307dd64aa05135bf1d206635e5d76052fac843aca69abe1a1efb4a9d0829b11d4968e6337a3a90d21c2488cdeb0b9ce97901b1b49ddec9bc2bf41a3b76c68b380d8bc2a08bad08aad8e3a8f68",
    }
}

Step 3a: Redirect your customer to the redirectUrl provided in the response.

There, the customer will choose their preferred payment method and perform the actual payment.

When customer payment flow is completed, aborted or failed, the customer will be redirected to the relevant merchant redirect URL you have specified in your Globadyme Merchant dashboard.

Step 3b: Initiate a payment through API

Alternatively, it is possible to use your own payment page and send the information to the Globadyme API.

Url: https://sandbox.globadyme.com/api/globadymeGateway/transaction/initiatePayment

Example:

{
    "encryptedTransaction": "0f628205c22995c7eda38b96b336df05421b3464055fc756cb8a61ce2d052bf35f80a0d43fc6541152a58644b2952927b86e5333b4d0d94c8a30d5b3c17b3fd68af5246aa0e37b261375646d519c2539d4f6fd01254474ab66221835a9604ad27c7d8d3a31d601c3937e322b0d5c87482229e008ccd28dce88fd98cbfba4014a8c6a999698628ca08b8fc8988696cf08fac22c61a431c9d0384255b3e7ac3ffdc264446bb45ac5dbad38411a93ce2d3ae11f2a0b078e6dea72c662152d5e862e5e59e26ce32a4f51448c3bec26d8b211706cbc83e70fa87536ced4cacdb2f844b5651e3d6ce5aa7dbb57b556b1cafda0f2f9fd9742106d324a857e577dd47bf50031653f0554e0e3226b46783544734ed3c5136f03f6ce6ac9b39b126395671169c0342c7807e0332342d090b58890be9a872be5d7b23b6b8f0bd1d1ac600330700f247a2cb2b77e345549fe4d743b3c02ee116640e9cc338fb9023b21f19b69bc2515ed3bf498d003a7c495d2fb520b864e580242ef94a294db6f431015bf5c644e23f09e94718635eafccfbd7c946654d0ba9560fe7d57dec1b2209d713c3a6767a76ede2ff6d2b51b17d9d7073c078419599e6675815776b9285af5e661b80f6402bb2c85a9edadae2817bb50b9f069610e0376b16b88a2d1f9cef2820e5be7b2e7deb52d2ab85d10f5ca526cf7feb20408b74481ef7ec579af79092e4afdd66dbe63e906eadf316fc5a193f52af7db22532e793ba5c6e2e35e1a4dbf8e2a6c9aa65cfc8c4e8c8617a89d24dc93c2050cf2fcc5f2c24eff778c3a3ff83183eb4117a2ce55f0f09bf0282c3d328f423efb4c30cebcfaf9d25ebfbf55341d099561aac5a1bc1d9d33d40457f3b5cb55c5b53c0fc1dacc47e4f4ec5a64c282d27664375d0ed30986ebcb77532be586c14cdca31ffc9dfffbc5fa1d76d0de0524aff98db0040b58802371ac48632aec8a160ff023bbda12c36ca1d2b85dbde0513884f6f233c73c5dc32bb4216ffe9c5e93e12c0390a1b9ba1dbf81a9bb251c79903a09781fb1bfa5e821e5ab8af980e01ba2629fb957299517cab38ce42888f90d72e8cc8a96d70b96c42446e325c66734bd77e62ddc5c0d73e1551cd1dd5cdccea169fc21e23c5a2ba674de86ba4c8a573933b224bb538141e06d639b6cf0073894104315c4b0f581e191bda8ed5ed3ae2779db24c3a49837b02f2652bd317f3cb28040eb0885acd4edb1ac4240e56dfdbddd10fc2edf9946f11a819369f665de2753bab777583e113f7f8c847e34be6b0d3a6cf103f2d01cb90a583589b0d82b7aa3d6210d9673dca12166bf507d175dd15d2ef06699f9009ec2478ee73a49d3864ec5c9281068f77978594755ad84d347f892aa2099c91633e3cf328965f67e17470d39daa4b35ab13983ee6f0486f9372b7a79329595640f9ef6196b211c5f3ebb7f887d58cb69a6c20db44971832a936a4c0dbfeb37dfed7b6336adf1d3529f140306316a5eb12b9539edc16d3410800197ae196ef02e6150d47d1adc11a0c3d1f37d6ed5b3db19be19e557ad92da8286249536ed6116178ae0a08dedec6c7ce76f7d52c2eacb4a0c473d4387ad23784912a61d7948d8a9ecf5ff32e040ae889a6cd49884aeea545c12fb7752a2c05ddb7d42c4b23b59d2062d31a1235f8bb3b9b5426d484403b73a8a63be591292d80151ec2ad345072d153d6e0b11f6689b8472c4dad421e06502392bea0fbf66fb8d93613d20104ee8d8c2f7865a4a6021aa315e25657fd9aaedcd8429fae352542231bfafedfbdd83b8aad72ecfa40703b27306e4956eb6f96b7473fab254e6d8e705add9fa2910a2e673055dd716f0d9ccce060cf15e5022864565ec36bcec430f06ea70f8fe3eeafeb301517a9e4af367794803ea2d0efe8ddb7ab24a36d55d07c3b9e77a38599c6b03f84ceb830eb1fa1944f66efe9b24179c53e821692ec0e2ced394f8971ccdd294e9a9fb379e978fd0b06afc928dd7da8149060cadb0ebd38d936eb019745c00d1f0e7a4d6879eb7ce1e0734e1bab61eb733fb184e9fde20c140096f068605de0e5b3ea112e46d0cee8f84b159884d4169f3b702f12bf832ea415db0abf68a72917b3ad0e0c7c17d788f3547e896add17f442307dd64aa05135bf1d206635e5d76052fac843aca69abe1a1efb4a9d0829b11d4968e6337a3a90d21c2488cdeb0b9ce97901b1b49ddec9bc2bf41a3b76c68b380d8bc2a08bad08aad8e3a8f68",
    "requestId": "852f0c72-0024-4070-9ac7-563eeb4755f6",
    "paymentMethod": "IDEAL",
    "bank": "ING"
}

Mandatory elements:

  • encryptedTransaction: The encrypted transaction as received in the return url in step 2.

  • requestId: The request ID as received in step 2.

  • paymentMethod: The payment method as chosen by the consumer. Case insensitive. Valid payment methods:

    • IDEAL: In case of an IDEAL payment, the ‘bank’ element must be specified. Valid bank values:

      • NN

      • ING

      • ABNAMRO

      • KNAB

      • ASN

      • RABO

      • BUNQ

      • REGIOBANK

      • REVOLUT

      • SNS

      • TRIODOS

      • VANLANSCHOT

      • YOURSAFE

      • N26

    • PAYPAL

    • KLARNA

    • CREDITCARD

    • EPS

    • GIROPAY

    • SOFORT

    • PAYCONIQ

    • SEPA

    • BANCONTACT

Step 4: Receive a callback from Globadyme. 

You will receive a callback from Globadyme.

This will be POSTed to the (https) endpoint you specified in your Globadyme Merchant dashboard.

The callback will contain status information about your transaction.

It will also contain a requestId, which will be the same as the requestId you received as a response to the requestPayment call. You can use this requestId to match the callback to a request you sent. RequestId will never show up on any bank statements.

The message contains a signature header. This header is a SHA-512 hash of the JSON body and the callback secret (which is provided by Globadyme). You should use this to verify the authenticity of the message. 

Example in Java:signatureHash = bytesToHex(digest.digest((notification + notifySecret).getBytes()));

Example of a callback:

{
    "id": "055ff314-6399-4350-8b8b-c9cd1e22a065",
    "amount": 10.00,
    "status": {
        "displayName": "Processed successfully",
        "name": "PROCESSED"
    },
    "paymentMethod": "IDEAL",
    "currency": "EUR",
    "country": "NL",
    "description": "TestPayment",
    "feeCalculation": {
        "sellPercentage": 0.00,
        "sellCents": 15
    },
    "timestamp": "2024-01-20T13:05:51.948873470Z",
    "requestId": "852f0c72-0024-4070-9ac7-563eeb4755f6"
}

Step 5: Optional - Request payment status

Besides processing notifications described in the previous chapter, there is the option of requesting a transaction's status based on the requestId.

Url: https://sandbox.globadyme.com/globadymeGateway/transaction/getPaymentByRequestId

The endpoint expects a GET request with an application/json Content-Type.

Example of a request:

{
    "password": "apiPassword", // Merchant transaction password, provided by Globadyme
    "merchantId": "7699cab7-2dfa-4981-9c90-0d0c93c801ac", // Merchant UUID
    "requestId": "3bdf2480-4ae6-44a1-bce0-3710d89cbfc4"
}

Mandatory fields:

  • password: The API password as provided by Globadyme

  • merchantId: The merchant UUID as provided by Globadyme

  • requestId: The requestId as received in response to the concerning /requestPayment call

Example of a response:

{
    "message": "PaymentByRequestId",
    "details": {
        "requestId": "3bdf2480-4ae6-44a1-bce0-3710d89cbfc4",
        "transactions": [
            {
                "id": "f791c1e4-39eb-4bd1-8201-0460d560fef1",
                "created": "2024-01-15T17:21:26.550656Z",
                "status": "PROCESSED",
                "amount": 10.0,
                "currency": "EUR",
                "country": "NL",
                "paymentMethod": "iDEAL",
                "accountholderName": "Oebele de Rekeninghouder",
                "requestId": "3bdf2480-4ae6-44a1-bce0-3710d89cbfc4"
            }
        ]
    }
}

Note: The response object contains a ‘transactions’ list because it is possible that one request has produced more than one transaction. For example: an end user has initiated a payment using payment method A and decided not to complete the payment. After pressing ‘back’, the end user initiated a new payment using payment method B.  In this case, there can be more than one transaction with the same requestId:

{
    "message": "PaymentByRequestId",
    "details": {
        "requestId": "3bdf2480-4ae6-44a1-bce0-3710d89cbfc4",
        "transactions": [
            {
                "id": "c018be0a-a633-40c8-805a-a2dfd6090af8",
                "created": "2024-01-30T22:20:25.822136Z",
                "status": "PENDING",
                "amount": 10.0,
                "currency": "EUR",
                "country": "NL",
                "paymentMethod": "Creditcard",
                "accountholderName": "Oebele de Rekeninghouder",
                "requestId": "3bdf2480-4ae6-44a1-bce0-3710d89cbfc4"
            },
            {
                "id": "b88e446c-6889-4cc1-958e-10a4ed951ace",
                "created": "2024-01-30T22:20:32.424212Z",
                "status": "PROCESSED",
                "amount": 10.0,
                "currency": "EUR",
                "country": "NL",
                "paymentMethod": "iDEAL",
                "accountholderName": "Oebele de Rekeninghouder",
                "requestId": "3bdf2480-4ae6-44a1-bce0-3710d89cbfc4"
            }
        ]
    }
}

In this case one can check if there is any transaction with a “PROCESSED” status to confirm that a successful payment has been made.

  • No labels