OutlinePay Docs문서 openapi.json
API ReferenceAPI 레퍼런스

OutlinePay APIOutlinePay API

OutlinePay is a processor-agnostic payments API for merchant platforms looking to offer US payments. We provide headless capabilities for merchant management, checkout pages, payment links, refunds, disputes, and event webhooks. OutlinePay는 미국 결제를 제공하려는 가맹점 플랫폼을 위한, 결제 처리사에 종속되지 않는 결제 API입니다. 가맹점 관리, 체크아웃 페이지, 결제 링크, 환불, 분쟁, 이벤트 웹훅을 헤드리스 방식으로 제공합니다.

Prefer tooling? Download the OpenAPI spec and import it into Postman, Insomnia, or a client generator.도구를 선호하시나요? OpenAPI 명세를 내려받아 Postman, Insomnia 또는 클라이언트 생성기에 가져오세요.

Conventions규약

Requests요청

Authentication인증

Authenticate every request with your partner secret key as a Bearer token. Keys come in test (olp_sk_test_…) and live (olp_sk_live_…) variants over the same API. Each is shown once at creation and stored hashed.모든 요청은 파트너 시크릿 키를 Bearer 토큰으로 사용해 인증합니다. 키는 동일한 API에서 테스트용(olp_sk_test_…)과 라이브용(olp_sk_live_…) 두 종류로 발급되며, 각 키는 생성 시 한 번만 표시되고 해시된 형태로 저장됩니다. Create yours on the API keys page in the Developers hub.키는 개발자 허브의 API 키 페이지에서 발급받으실 수 있습니다.

HTTP
Authorization: Bearer olp_sk_test_YOUR_KEY

Errors오류

Errors return a matching HTTP status and a JSON body of two keys: code classifies the refusal, and details describes it, one entry per problem found.오류가 발생하면 해당하는 HTTP 상태 코드와 함께 두 개의 키로 이루어진 JSON 본문을 반환합니다. code는 거부의 종류를 나타내고, details는 발견된 문제를 항목 하나당 하나씩 담습니다.

JSON
{ "error": { "code": "not_found", "details": [
    { "param": "merchant_id", "message": "No such merchant: \"mrc_bogus\"." }
] } }
Codes코드
invalid_request (400, or 409 and 422 on Attach a processor), not_found (404 or 400, see below), payment_method_not_enabled (400), authentication_error (401), merchant_not_onboarded (409), merchant_terms_not_accepted (409), partner_sites_incomplete (409), payments_paused (409), refunds_paused (409), idempotency_conflict (409), rate_limited (429), processor_error (502). Attach a processor is the one endpoint where invalid_request is not a 400. A merchant that already has an account for the processor is a 409, and a merchant whose country we do not onboard in yet is a 422.invalid_request (400, 결제 처리사 연결에서는 409 또는 422), not_found (404 또는 400, 아래 참조), payment_method_not_enabled (400), authentication_error (401), merchant_not_onboarded (409), merchant_terms_not_accepted (409), partner_sites_incomplete (409), payments_paused (409), refunds_paused (409), idempotency_conflict (409), rate_limited (429), processor_error (502). invalid_request가 400이 아닌 곳은 결제 처리사 연결 엔드포인트 한 곳뿐입니다. 해당 처리사의 계정을 이미 보유한 가맹점은 409, 아직 저희가 온보딩하지 않는 국가의 가맹점은 422입니다.
details
Never empty, and every entry carries a message. A refusal is a single entry everywhere except write-time validation, where each refused field is its own entry: unknown fields first, then value checks, in this reference's field order. Every entry shares the top-level code. A response without error.details did not come from the API. Treat it as a transient system error and retry.항상 1건 이상이며, 모든 항목에 message가 담깁니다. 저장 시점 검증을 제외한 모든 거부는 항목이 1건입니다. 저장 시점 검증에서는 거부된 필드마다 항목이 하나씩 생기며, 문서에 없는 필드가 먼저, 값 검사가 그 뒤에, 이 문서의 필드 순서대로 정렬됩니다. 모든 항목은 최상위 code와 같은 코드를 공유합니다. error.details가 없는 응답은 API가 생성한 것이 아닙니다. 일시적인 시스템 오류로 간주하고 재시도해 주십시오.
404 or 400404와 400의 구분
An id that names nothing always carries not_found, and the status says where you put it: 404 in the path, 400 as a query parameter or a body field. One that does not begin with the resource's OutlinePay prefix gets a second sentence naming the prefix we expected: OutlinePay merchant ids begin with "mrc_". A path that matches no endpoint, or a real one in a method it does not take, is a 404 not_found too, with the method and path quoted back.아무것도 가리키지 않는 id는 언제나 not_found 코드를 담으며, HTTP 상태는 그 id를 어디에 두셨는지를 알려드립니다. 경로에 있으면 404, 쿼리 파라미터나 본문 필드로 전달하신 경우에는 400입니다. 해당 리소스의 OutlinePay 접두사로 시작하지 않는 id에는 저희가 기대한 접두사를 알려드리는 문장이 한 줄 덧붙습니다. 예를 들면 OutlinePay merchant ids begin with "mrc_".입니다. 어떤 엔드포인트와도 일치하지 않는 경로, 또는 존재하는 경로를 지원하지 않는 메서드로 호출한 경우에도 not_found와 404로 응답하며, 요청하신 메서드와 경로를 그대로 인용해 돌려드립니다.
Malformed values형식이 잘못된 값
A value we cannot accept at all, rather than one we looked up and could not find, is invalid_request with a 400. Both kinds quote the offending value back and name its field in the entry's param. A value the processor refuses when we forward it answers the same way, with the processor's own sentence in the entry's processor_message.조회해 보았으나 찾지 못한 값이 아니라 애초에 받을 수 없는 값은 invalid_request와 400으로 응답합니다. 두 경우 모두 문제가 된 값을 그대로 인용해 돌려드리고, 해당 필드 이름을 항목의 param에 담습니다. 전달한 값을 결제 처리사가 거부한 경우에도 같은 방식으로 응답하며, 처리사 자신의 설명이 항목의 processor_message에 담깁니다.
Unknown parameters문서에 없는 파라미터
A parameter an endpoint does not document is refused, not ignored. The refusal names the nearest parameter that endpoint does take, when there is one. Keys inside a documented object and metadata are not checked.해당 엔드포인트가 문서화하지 않은 파라미터는 무시하지 않고 거부합니다. 거부 응답에는 해당 엔드포인트가 받는 파라미터 중 가장 가까운 이름이 있으면 함께 담깁니다. 문서화된 객체 안의 키와 metadata는 검사하지 않습니다.
param
Present on an entry about exactly one request field: that field's name, in the API's spelling.정확히 하나의 요청 필드가 원인인 항목에 포함됩니다. API 표기 그대로의 해당 필드 이름입니다.
doc_url
Present on an entry when a section here explains the fix: a link straight to it. Every refusal that needs more than its own message to clear carries one.이 문서의 한 섹션이 해결 방법을 설명할 때 항목에 포함됩니다. 그 섹션으로 바로 연결되는 링크입니다. 메시지만으로 해결할 수 없는 모든 거부 응답에 포함됩니다.

Idempotency멱등성

Send an Idempotency-Key header on any POST to make retries safe: two attempts carrying the same key are the same operation, however far apart they arrive. Optional everywhere except Create a refund, where it is required.재시도를 안전하게 하시려면 POST 요청에 Idempotency-Key 헤더를 보내십시오. 같은 키를 가진 두 요청은 시간이 아무리 벌어져도 같은 작업으로 처리됩니다. 환불 생성에서는 필수이며, 그 외의 모든 엔드포인트에서는 선택입니다.

Generating a key키 생성 방법
Any unique string. A UUID v4 is the usual choice. Mint it when the business action is created in your system (the order, the refund your support tool records), store it on that action, and send the same key on every retry of it. Two separate $5 refunds are two actions, so they carry two keys. A fresh key per HTTP attempt defeats the mechanism.고유한 문자열이면 어떤 값이든 되며, 보통 UUID v4를 사용합니다. 귀사 시스템에서 해당 업무 작업(주문, 상담 도구가 기록한 환불 건)이 만들어질 때 키를 발급해 그 작업에 저장해 두시고, 그 작업을 재시도할 때마다 같은 키를 보내 주십시오. 서로 다른 5달러 환불 두 건은 별개의 작업이므로 키도 두 개입니다. HTTP 시도마다 새 키를 발급하시면 이 장치가 무력화됩니다.
What a retry gets재시도가 받는 응답
The same key with the same body replays the stored response, status and all. Nothing executes twice.같은 키에 같은 본문이면 상태 코드까지 포함해 저장된 응답을 그대로 재생합니다. 어떤 것도 두 번 실행되지 않습니다.
Conflicts충돌
The same key with a different body is refused with 409 idempotency_conflict, and so is a retry that arrives while the first attempt is still running.같은 키에 다른 본문이면 409 idempotency_conflict로 거부됩니다. 첫 시도가 아직 실행 중일 때 도착한 재시도도 마찬가지입니다.
Server errors서버 오류
A 5xx response is not stored, so retrying after one executes fresh rather than replaying the failure.5xx 응답은 저장되지 않으므로, 서버 오류 후의 재시도는 실패를 재생하는 대신 새로 실행됩니다.
Scope and lifetime범위와 유효 기간
Keys are scoped to your account and to the key's mode, so the same string in test and live never collides. They are kept for 24 hours. After that, reusing the string starts a new request.키는 귀사 계정과 키의 모드 단위로 관리되므로, 같은 문자열이라도 테스트와 라이브에서 충돌하지 않습니다. 24시간 보관되며, 그 이후에 같은 문자열을 다시 사용하시면 새 요청으로 처리됩니다.

PHP has no built-in UUID function, and none is needed:PHP에는 UUID 생성 함수가 내장되어 있지 않지만, 별도의 라이브러리는 필요하지 않습니다.

<?php
// Any unique string works. 32 random hex characters, no library needed:
$key = bin2hex(random_bytes(16));

// Or the same entropy shaped as a standard UUID v4, if you prefer that:
function uuid_v4(): string {
    $b = random_bytes(16);
    $b[6] = chr((ord($b[6]) & 0x0f) | 0x40); // version
    $b[8] = chr((ord($b[8]) & 0x3f) | 0x80); // variant
    return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($b), 4));
}

Pagination페이지네이션

List endpoints are cursor-based and newest-first. Pass limit (1–100, default 20) and starting_after=<id>. Responses are { "data": [...], "has_more": bool }.목록 엔드포인트는 커서 기반이며 최신순으로 반환합니다. limit(1~100, 기본값 20)과 starting_after=<id>를 전달하십시오. 응답 형식은 { "data": [...], "has_more": bool }입니다.

Walking a list목록 순회 방법
Send the id of the last object you received as the next starting_after, and stop when has_more comes back false.직전에 받으신 마지막 객체의 id를 다음 starting_after로 전달하시고, has_more가 false로 오면 중단하십시오.
limit
One we cannot read as an integer is refused. One outside 1–100 is clamped instead, so limit=500 returns 100 rather than an error.정수로 읽을 수 없는 값은 거부됩니다. 1~100을 벗어난 값은 거부하지 않고 범위 안으로 조정하므로, limit=500은 오류가 아니라 100건을 반환합니다.
starting_after
A cursor that names nothing is a 400 with not_found, like any other unknown id. It resolves against the request's own filters, so pairing it with a filter that excludes it is refused the same way.아무것도 가리키지 않는 커서는 다른 알 수 없는 id와 마찬가지로 not_found 코드와 함께 400으로 응답합니다. 커서는 해당 요청의 필터와 함께 조회되므로, 커서가 가리키는 객체를 제외하는 필터와 함께 전달하시면 동일하게 거부됩니다.

Filtering lists목록 필터링

Every list takes the same filters wherever they apply, and they combine with AND. Each endpoint's parameter table says which it has.모든 목록 엔드포인트는 해당되는 곳마다 같은 필터를 받으며, 필터는 AND로 결합됩니다. 각 엔드포인트의 파라미터 표에 어떤 필터가 있는지 나와 있습니다.

merchant_id, payment_id
The object's owner. Refunds and disputes belong to a merchant through their payment, so merchant_id works there too. An id that names nothing is a 400 with not_found, like any other id you pass.객체의 소유자입니다. 환불과 분쟁은 결제를 통해 가맹점에 속하므로 merchant_id를 그곳에서도 쓰실 수 있습니다. 아무것도 가리키지 않는 id는 다른 id와 마찬가지로 not_found 코드와 함께 400으로 응답합니다.
status
The object's own state, one value. Anything outside the object's vocabulary is a 400 with invalid_request listing what is allowed.객체 자체의 상태이며 값 하나를 받습니다. 해당 객체의 상태 값이 아닌 값은 허용되는 값 목록과 함께 invalid_request 코드로 400 응답합니다.
created_after, created_before
Bounds on the object's created_at, the timestamp every object carries, so you can check the boundary against what you see. created_after is inclusive and created_before exclusive, so consecutive months chain without overlap: created_after=2026-08-01&created_before=2026-09-01, then created_after=2026-09-01. Both take an ISO 8601 timestamp or a bare date, which means midnight UTC. Note that a payment minted by a payment link is created when the customer pays, and a dispute when the processor reports it.모든 객체가 가진 created_at 시각의 범위이므로, 응답에 보이는 값으로 경계를 확인하실 수 있습니다. created_after는 같은 시각을 포함하고 created_before는 제외하므로, 연속된 달이 겹치지 않고 이어집니다. created_after=2026-08-01&created_before=2026-09-01 다음에 created_after=2026-09-01을 쓰시면 됩니다. 두 값 모두 ISO 8601 시각 또는 날짜만 받으며, 날짜만 주시면 UTC 자정으로 해석됩니다. 결제 링크로 생성된 결제는 고객이 결제한 시점에, 분쟁은 결제 처리사가 보고한 시점에 생성된다는 점을 참고하십시오.

Rate limits요청 한도

Requests are limited per API key: currently 100 reads and 60 writes per minute.요청은 API 키별로 제한되며, 현재 분당 읽기 100회, 쓰기 60회입니다.

Over the limit, requests return 429 rate_limited with a Retry-After header (in seconds) and nothing is processed. Wait that long and retry the same call.한도를 초과하면 429 rate_limited와 함께 Retry-After 헤더(초 단위)가 반환되며 아무것도 처리되지 않습니다. 해당 시간만큼 기다리신 뒤 같은 호출을 다시 시도해 주십시오.

Amounts, timestamps & ids금액 · 시각 · 식별자

  • Amounts are integers in the currency's minor unit: 10000 is $100.00 in USD.금액은 해당 통화의 최소 단위 정수입니다. 예를 들어 USD에서 10000은 $100.00입니다.
  • Timestamps are ISO 8601 UTC strings.시각은 ISO 8601 UTC 문자열입니다.
  • Ids are prefixed and opaque (pay_, link_, re_, mrc_, dp_, we_, evt_). Their length and prefix can change, so store them as text and do not parse them. Numeric ids never appear.ID는 접두사가 붙은 불투명한 값입니다(pay_, link_, re_, mrc_, dp_, we_, evt_). 길이와 접두사는 바뀔 수 있으므로 문자열로 저장하시고 파싱하지 마십시오. 숫자 ID는 노출되지 않습니다.
  • Every resource names its type in object (payment, merchant, ...), which is also how an event's data says what it carries.모든 리소스는 object 필드로 자신의 타입을 밝힙니다(payment, merchant 등). 이벤트의 data가 무엇을 담고 있는지도 이 필드로 알 수 있습니다.

Stability안정성

/v1 is a namespace, not a version number. A change to how an endpoint behaves is dated in the Changelog rather than announced by a new path. If a /v2 ever appears it will be because the conventions on this page changed, and /v1 will keep working beside it./v1은 버전 번호가 아니라 네임스페이스입니다. 엔드포인트의 동작이 바뀌는 변경은 새 경로로 알려드리지 않고 변경 사항에 날짜와 함께 기록합니다. 언젠가 /v2가 생긴다면 그것은 이 페이지의 규약 자체가 바뀌었기 때문이며, 그때에도 /v1은 그 옆에서 계속 동작합니다.

These are additive and arrive in any release:다음은 기존 동작에 더해지는 변경이며, 어느 배포에서나 도착할 수 있습니다.

  • A new endpoint.새로운 엔드포인트.
  • A new optional parameter on an existing request.기존 요청에 추가되는 선택 파라미터.
  • A new field on an existing response object.기존 응답 객체에 추가되는 필드.
  • A new event type.새로운 이벤트 타입.
  • A new value in an enum you already read, such as a payment status or an error code.이미 읽고 계신 열거값에 추가되는 값. 예를 들어 새로운 결제 상태나 오류 코드입니다.
What that asks of you연동에 필요한 것
Ignore fields you do not recognize rather than failing on them. Treat an unfamiliar enum value as one you do not handle yet, not as invalid data. Match the error codes you handle and let the rest fall to a default.알지 못하는 필드는 오류로 처리하지 마시고 무시하십시오. 처음 보는 열거값은 잘못된 데이터가 아니라 아직 처리하지 않는 값으로 다루십시오. 처리하시는 오류 코드만 분기하시고 나머지는 기본 처리로 넘기십시오.
Changes to behavior you rely on의존하고 계신 동작의 변경
Renaming or removing a field, changing its type, changing what a value means, changing the status or error code for a request that has not changed, or removing an endpoint, an event type or an enum value. Each one is dated in the Changelog and carries one of the two labels below.필드의 이름 변경 또는 삭제, 필드 타입 변경, 값의 의미 변경, 동일한 요청에 대한 상태 코드나 오류 코드 변경, 엔드포인트와 이벤트 타입과 열거값의 삭제입니다. 각 변경은 변경 사항에 날짜와 함께 기록되며 아래 두 라벨 중 하나가 붙습니다.
Breaking
A documented request whose answer we changed. customer_email became customer.email, so an integration reading the old field reads nothing.문서에 있던 요청의 응답이 바뀐 변경입니다. customer_email이 customer.email이 되었으므로, 이전 필드를 읽던 연동은 아무것도 읽지 못합니다.
Stricter
Input we never documented and no longer accept, where it used to be ignored or answered misleadingly. limit=abc used to return a single row and is now refused. Code that sent only documented values is unaffected.문서에 없던 입력을 더 이상 받지 않는 변경입니다. 이전에는 무시되거나 오해를 부르는 응답을 받던 값입니다. limit=abc는 이전에 한 건을 반환했으나 이제는 거부됩니다. 문서에 있는 값만 보내신 코드는 영향을 받지 않습니다.
Current status현재 상태
/v1 is frozen. A change to behavior you rely on no longer ships to an existing integration. If one is ever needed, you hear about it first, it arrives as a dated version you choose to move to, and an integration that does nothing keeps the behavior it was written against./v1은 동결되었습니다. 의존하고 계신 동작을 바꾸는 변경은 더 이상 기존 연동에 배포되지 않습니다. 언젠가 그런 변경이 꼭 필요해지면 먼저 안내드리고, 날짜가 붙은 버전으로 제공되어 귀사가 원하실 때 옮겨 가시며, 아무것도 하지 않은 연동은 작성 당시의 동작을 그대로 유지합니다.
Never held back by a version버전과 무관하게 적용되는 것
A fix reaches you when the behavior it corrects was never documented. Security fixes, and corrections to amounts, reach you immediately and without exception.문서에 없던 동작을 바로잡는 수정은 버전과 상관없이 적용됩니다. 보안 수정과 금액을 바로잡는 수정은 예외 없이 즉시 적용됩니다.
Keep a regression test회귀 테스트를 갖추십시오
Assert on the fields your code reads, across a full lifecycle on your test key: create a payment, complete it, take the webhook, read the result back. Run it before go-live, and again after any entry labeled Breaking or Stricter. The Testing page lists the values that drive each scenario.코드가 읽는 필드를 테스트 키로 전체 흐름에 걸쳐 검증하십시오. 결제를 생성하고, 완료하고, 웹훅을 받고, 결과를 다시 조회하는 흐름입니다. 라이브 전환 전에 한 번, 그리고 Breaking이나 Stricter 라벨이 붙은 항목이 나올 때마다 다시 실행하십시오. 각 시나리오를 일으키는 값은 테스트 페이지에 정리되어 있습니다.

Conventions규약

Objects & fields객체와 필드

Metadata메타데이터

Merchants, payments, refunds and payment links accept metadata: your own key/value pairs, for tying our objects back to your records.가맹점, 결제, 환불, 결제 링크는 metadata를 받습니다. 직접 정의하신 키/값 쌍으로, OutlinePay 객체를 귀사의 기록과 연결하는 데 사용하십시오.

Opaque to us내용을 해석하지 않음
We never interpret the contents. They are stored, returned on every read, and carried on every event that object emits. A payment's, refund's or payment link's is also forwarded to the processor. A merchant's is not.OutlinePay는 내용을 전혀 해석하지 않습니다. 저장되고, 모든 조회 시 반환되며, 해당 객체가 발행하는 모든 이벤트에 실려 전달됩니다. 결제, 환불, 결제 링크의 메타데이터는 결제 처리사에도 전달되며, 가맹점의 메타데이터는 전달되지 않습니다.
Editing수정
Payments, refunds and payment links take it at creation only. A merchant's is also edited with Update a merchant, key by key: a key sent with a value is set, a key sent blank is removed, and keys left out are kept.결제, 환불, 결제 링크는 생성 시에만 설정할 수 있습니다. 가맹점의 메타데이터는 가맹점 수정에서 키 단위로 수정하실 수도 있습니다. 값과 함께 보내신 키는 설정되고, 빈 값으로 보내신 키는 삭제되며, 보내지 않으신 키는 그대로 유지됩니다.
Limits제한
At most 50 pairs, keys up to 40 characters, values up to 500, stored as strings. Nested objects and arrays are rejected.최대 50쌍이며, 키는 40자, 값은 500자까지이고 문자열로 저장됩니다. 중첩된 객체와 배열은 거부됩니다.
Reserved keys예약된 키
Keys beginning outlinepay_, plus outline_fee and partner_fee, are ours and are rejected.outlinepay_로 시작하는 키와 outline_fee, partner_fee는 OutlinePay가 사용하며, 요청이 거부됩니다.
Never secrets비밀 정보 금지
Payment, refund and payment link metadata reaches the processor and is visible in their dashboard.결제, 환불, 결제 링크의 메타데이터는 결제 처리사까지 전달되며 처리사의 대시보드에서 그대로 보입니다.

Forward-only fields전달 전용 필드

Fields marked forward-only are passed to the payment processor to prefill onboarding, then discarded.전달 전용(forward-only)으로 표시된 필드는 온보딩을 미리 채우기 위해 결제 처리사로 전달된 뒤 폐기됩니다.

Which fields해당 필드
tax_id, and every field under representative, supplied when you attach a processor.tax_id 및 representative 하위의 모든 필드이며, 결제 처리사를 연결하실 때 전달합니다.
Never stored저장하지 않음
They are never stored or returned, so they cannot appear in a later GET, an event payload, or a backup.이 값들은 저장되지도 반환되지도 않으므로, 이후의 GET 응답이나 이벤트 페이로드, 백업에 나타날 수 없습니다.
Everything else그 외 전부
Everything in a merchant's business is stored and comes back on the merchant.가맹점의 business에 포함된 모든 값은 저장되며 가맹점 객체로 반환됩니다.

Merchant-owned fields가맹점 소유 필드

Fields marked merchant-owned belong to the merchant once a processor is attached: the processor gives them ownership, so only they can change the value.가맹점 소유(merchant-owned)로 표시된 필드는 결제 처리사가 연결되는 순간 가맹점의 것이 됩니다. 결제 처리사가 소유권을 넘기므로 가맹점만 값을 변경할 수 있습니다.

Which fields해당 필드
product_description, industry_code, statement_descriptor and phone.product_description, industry_code, statement_descriptor, phone입니다.
How they change변경되는 방식
The merchant edits them in the processor's account-management component. We write the new value back onto the merchant and emit merchant.updated.가맹점이 결제 처리사의 계정 관리 컴포넌트에서 수정합니다. OutlinePay는 변경된 값을 가맹점 객체에 다시 반영하고 merchant.updated 이벤트를 발행합니다.
Via the APIAPI를 통한 변경
Create a merchant and Update a merchant accept them until a processor is attached. After that, Update a merchant rejects them.결제 처리사를 연결하기 전까지는 가맹점 생성과 가맹점 수정 모두에서 받습니다. 연결 이후에는 가맹점 수정에서 거부됩니다.

Processor-agnostic values프로세서 독립 값

Some enums, business.structure and the account-session components, use OutlinePay's own vocabulary rather than any one processor's. We translate each value to your processor's equivalent when we forward it, and store and return the OutlinePay value, so the same words work no matter which processor is behind the account.일부 enum과 business.structure, 그리고 계정 세션 컴포넌트는 특정 결제 처리사의 용어가 아니라 OutlinePay 자체 용어를 사용합니다. 전달 시 각 값을 해당 결제 처리사의 대응 값으로 변환하며, 저장하고 반환할 때는 OutlinePay 값을 사용합니다. 따라서 계정 뒤에 어떤 처리사가 있든 동일한 용어가 그대로 동작합니다.

Fields beginning processor_ are the exception: they carry the processor's own value, outside this contract. Read them, don't branch on them.processor_로 시작하는 필드는 예외입니다. 저희 값이 아니라 처리사의 값을 담으며 이 계약의 범위 밖에 있습니다. 읽으시되, 분기 조건으로는 쓰지 마십시오.

Write-time validation저장 시점 검증

A value the payment processor is known to refuse is refused when you send it, as 400 invalid_request with one details entry per refused field, so it cannot be stored at creation and then fail when the processor is attached.결제 처리사가 거부하는 것으로 확인된 값은 전송 시점에 곧바로 거부됩니다. 거부된 필드마다 details 항목을 하나씩 담은 400 invalid_request로 응답하므로, 생성 시에는 저장되었다가 처리사 연결 시점에 실패하는 일이 없습니다.

URLsURL
business.url must be a full http(s) address with a domain name, e.g. https://acme-trading.com. An IP address, a non-standard port, or a unicode domain (send its punycode xn-- form) is refused.business.url은 도메인 이름을 포함한 완전한 http(s) 주소여야 합니다. 예: https://acme-trading.com. IP 주소, 비표준 포트, 유니코드 도메인(퓨니코드 xn-- 형식으로 보내 주십시오)은 거부됩니다.
Emails이메일
The merchant's email, representative.email and a payment's customer.email need a name, an @, and a dotted domain, in ASCII.가맹점 email, representative.email, 결제의 customer.email에는 ASCII로 된 이름, @, 점이 포함된 도메인이 필요합니다.
Addresses주소
An address sent with any field needs its country, and a business address must be in the merchant's own country. For a US address, postal_code is 5 digits or ZIP+4, and state is the two-letter USPS code. US insular areas (GU, VI, AS, MP) aren't served by the processor. A representative's home address may be in any country.어떤 필드든 주소를 보내실 때는 country가 필요하며, 사업장 주소는 가맹점 자신의 국가에 있어야 합니다. 미국 주소의 postal_code는 5자리 또는 ZIP+4, state는 두 글자 USPS 코드입니다. 미국 도서 지역(GU, VI, AS, MP)은 결제 처리사가 지원하지 않습니다. 대표자의 자택 주소는 어느 국가든 가능합니다.
Phones전화번호
business.phone and representative.phone must parse as a phone number. E.164 always works, and national formats the processor can parse also pass.business.phone과 representative.phone은 전화번호로 해석 가능해야 합니다. E.164가 안전한 형식이며, 처리사가 해석할 수 있는 국가별 형식도 통과합니다.
Category and descriptor업종 코드와 명세서 표기
business.industry_code must be one of the ISO 18245 merchant category codes we support. business.statement_descriptor is 5 to 22 characters, contains a Latin letter, and has no angle brackets.business.industry_code는 저희가 지원하는 ISO 18245 업종 코드(MCC) 중 하나여야 합니다. business.statement_descriptor는 5~22자이고, 라틴 문자를 하나 이상 포함하며, 꺾쇠괄호는 쓸 수 없습니다.
Identity신원 정보
tax_id is the 9-digit US EIN, hyphens welcome. representative.date_of_birth is a past ISO date, at least 13 years back.tax_id는 9자리 미국 EIN이며 하이픈은 있어도 됩니다. representative.date_of_birth는 과거의 ISO 날짜로, 최소 13년 전이어야 합니다.
What can still fail at attach처리사 연결 시에도 실패할 수 있는 것
Checks only the processor can make, chiefly its own list of placeholder and shared website domains (example.com and the like). Those answer 400 with the field in the entry's param and the processor's sentence in its processor_message.처리사만 확인할 수 있는 검사, 주로 자리표시용·공용 웹사이트 도메인(example.com 등)에 대한 처리사 자체 목록입니다. 이 경우 항목의 param에 필드 이름을, processor_message에 처리사의 설명을 담은 400으로 응답합니다.

Conventions규약

Money movement자금 흐름

Onboarding is required before charging결제 전 온보딩 필수

Creating a merchant and attaching a processor does not make it chargeable. The processor still has to verify the merchant, and until it does, Create a payment and Create a payment link both refuse with 409 merchant_not_onboarded.가맹점을 생성하고 결제 처리사를 연결하는 것만으로는 결제를 받을 수 없습니다. 결제 처리사가 가맹점을 검증해야 하며, 검증 전까지 결제 생성과 결제 링크 생성은 모두 409 merchant_not_onboarded로 거부됩니다.

How to clear it해결 방법
Call Create an account session for the merchant and render the returned client_secret with the onboarding component. Onboarding happens only in that component, on your own page. There is no link to email.해당 가맹점으로 계정 세션 생성을 호출하고, 반환된 client_secret을 온보딩 컴포넌트로 렌더링하십시오. 온보딩은 귀사의 페이지에 삽입된 이 컴포넌트에서만 진행됩니다. 이메일로 보낼 수 있는 링크는 없습니다.
How to know it worked완료 확인 방법
The merchant's status turns active and its processors[].verified turns true. merchant.updated fires at that moment.가맹점의 status가 active로 바뀌고 processors[].verified가 true가 됩니다. 이 시점에 merchant.updated 이벤트가 발송됩니다.
While you wait심사 대기 중
After the merchant submits, the processor reviews. The same 409 is returned with a message saying so, and there is nothing to retry until the status changes. processors[].requirements tells that apart from a merchant that still owes something: awaiting names whose move it is, and outstanding names what is left.가맹점이 제출을 마치면 결제 처리사가 심사합니다. 이 경우에도 동일한 409가 반환되며 메시지로 대기 상태임을 알려드립니다. 상태가 바뀌기 전까지 재시도하실 것은 없습니다. 아직 제출할 항목이 남은 가맹점과는 processors[].requirements로 구분하실 수 있습니다. awaiting이 다음 차례가 누구인지, outstanding이 무엇이 남았는지 알려줍니다.
The merchant terms가맹점 약관
The onboarding component also shows the OutlinePay merchant terms ahead of the processor's form. The merchant accepts once, for every processor. A merchant verified without ever seeing them (an integration that bypasses outlinepay.js) is refused with 409 merchant_terms_not_accepted, and the fix is the same onboarding component.온보딩 컴포넌트는 결제 처리사의 양식에 앞서 OutlinePay 가맹점 약관도 표시합니다. 가맹점은 한 번만 동의하면 모든 결제 처리사에 적용됩니다. 약관을 본 적 없이 검증된 가맹점(outlinepay.js를 거치지 않은 연동)은 409 merchant_terms_not_accepted로 거부되며, 해결 방법은 동일하게 온보딩 컴포넌트입니다.

Merchant pages가맹점 페이지

The processor emails your merchants directly about verification, disputes, payouts and documents, and those emails link to a page on the platform. It holds one set of page URLs for all of OutlinePay, so the links point at OutlinePay, and each click is forwarded to the page you registered for that merchant's surface. Register the six pages under Settings, Sites in the Developers hub.결제 처리사는 검증, 분쟁, 지급, 서류에 관해 귀사 가맹점에 직접 이메일을 보내며, 그 이메일은 플랫폼의 페이지로 연결됩니다. 처리사는 OutlinePay 전체에 대해 한 벌의 페이지 URL만 보관하므로 링크는 OutlinePay를 가리키고, 클릭할 때마다 해당 가맹점의 항목에 대해 귀사가 등록한 페이지로 전달됩니다. 개발자 허브의 설정, 사이트에서 여섯 페이지를 등록하십시오.

The six pages여섯 페이지
account_management, notifications and documents are pages where you mount the matching embedded component. payments, payouts and balances are plain pages where the merchant can see the thing, with no component needed.account_management, notifications, documents는 해당 임베디드 컴포넌트를 마운트하는 페이지입니다. payments, payouts, balances는 가맹점이 해당 내용을 볼 수 있는 일반 페이지이며 컴포넌트가 필요하지 않습니다.
What arrives전달되는 값
We append merchant_id (mrc_…) and processor to your URL so the page can open that merchant's view. The parameters say which merchant, never who is asking: sign the visitor in and check they belong to that merchant before showing anything.귀사 URL에 merchant_id(mrc_…)와 processor를 덧붙여 페이지가 해당 가맹점의 화면을 열 수 있게 합니다. 이 파라미터는 어느 가맹점인지를 말할 뿐 누가 요청하는지는 말하지 않습니다. 방문자를 로그인시키고 해당 가맹점 소속인지 확인한 뒤에 내용을 보여 주십시오.
Live mode라이브 모드
The processor will not onboard a live merchant until the pages exist. Create a merchant and Create an account session refuse with 409 partner_sites_incomplete, naming the missing pages, until all six are registered. Test mode does not need them.페이지가 등록되기 전까지 결제 처리사는 라이브 가맹점을 온보딩하지 않습니다. 여섯 페이지가 모두 등록될 때까지 가맹점 생성과 계정 세션 생성은 409 partner_sites_incomplete로 거부되며, 빠진 페이지를 함께 안내합니다. 테스트 모드에서는 필요하지 않습니다.

Paused payments결제 일시 중지

If we see suspicious activity, we can stop live payments while we look into it, and we email your admins when we do. Create a payment and Create a payment link then refuse with 409 payments_paused, and the checkouts already open close with them. Nothing is charged. The stop covers your whole account or a single merchant, and the message says which: when it names one merchant, your others keep charging.의심스러운 활동이 확인되면 확인하는 동안 라이브 결제를 중지할 수 있으며, 그때 귀사 관리자에게 이메일로 안내드립니다. 이 경우 결제 생성과 결제 링크 생성은 409 payments_paused로 거부되고, 이미 열려 있던 결제 페이지도 함께 닫힙니다. 청구되는 금액은 없습니다. 중지 범위는 계정 전체일 수도 있고 가맹점 한 곳일 수도 있으며, 어느 쪽인지는 메시지에 나옵니다. 가맹점 한 곳만 지정된 경우 다른 가맹점은 계속 결제를 받습니다.

Checkouts a customer already had고객이 이미 열어 둔 결제 페이지
Closed. Each payment behind one ends as expired and sends payment.expired, and resuming does not bring it back: create a fresh payment for that customer. A payment link survives, since it mints a new checkout on the next click.닫힙니다. 해당 페이지의 결제는 expired 상태로 종료되며 payment.expired 웹훅이 발송되고, 중지를 해제해도 되살아나지 않으므로 해당 고객에게는 결제를 새로 생성하셔야 합니다. 결제 링크는 다음 클릭에서 결제 페이지를 새로 만들기 때문에 그대로 사용하실 수 있습니다.
What keeps working계속 동작하는 것
Refunds, every read, webhooks, merchant onboarding, and the whole of test mode. A pause stops money coming in, never money going back: returning a customer's payment is exactly what you may need to do while one is on.환불, 모든 조회, 웹훅, 가맹점 온보딩, 그리고 테스트 모드 전체는 그대로 동작합니다. 일시 중지는 들어오는 돈을 막을 뿐 나가는 돈은 막지 않습니다. 중지된 동안 고객에게 결제를 돌려드리는 일이 필요할 수 있기 때문입니다.
What to do하실 일
Reply to the email we sent, or write to [email protected]. Nothing in your integration needs changing, and nothing is lost: your keys, merchants and endpoints are untouched. The same code can also mean a pause across all of OutlinePay rather than one about your account, and the message says which.보내 드린 이메일에 회신하시거나 [email protected]으로 연락해 주십시오. 연동을 수정하실 필요는 없으며 키와 가맹점과 엔드포인트는 그대로 유지됩니다. 같은 코드가 귀사 계정이 아니라 OutlinePay 전체의 일시 중지를 뜻할 수도 있으며, 어느 쪽인지는 메시지에 나옵니다.

Paused refunds환불 일시 중지

The separate stop, for the opposite problem. Where a payments pause stops money coming in, this one stops money going back out, and it exists for the case where a stolen key is refunding at volume. Create a refund refuses with 409 refunds_paused, and nothing is created.반대 상황을 위한 별도의 중지입니다. 결제 중지가 들어오는 돈을 막는다면 이 중지는 나가는 돈을 막으며, 탈취된 키가 대량으로 환불을 일으키는 경우를 위해 존재합니다. 환불 생성은 409 refunds_paused로 거부되고 아무것도 생성되지 않습니다.

Refunds already sent이미 보낸 환불
Unaffected. A refund already at the bank settles and sends refund.completed as usual. The stop only refuses new ones.영향을 받지 않습니다. 이미 은행으로 전달된 환불은 평소대로 정산되고 refund.completed 웹훅이 발송됩니다. 이 중지는 새 환불만 거부합니다.
What keeps working계속 동작하는 것
Payments, every read, webhooks, merchant onboarding, and the whole of test mode. The two stops are independent: one being on says nothing about the other.결제, 모든 조회, 웹훅, 가맹점 온보딩, 그리고 테스트 모드 전체는 그대로 동작합니다. 두 중지는 서로 독립적이어서 한쪽이 켜져 있다고 다른 쪽을 알 수는 없습니다.
What to do하실 일
Reply to the email we sent, or write to [email protected]. A refund refused this way was never created, so send it again once refunds are back. Like the payments stop, this one covers your account, one merchant, or all of OutlinePay, and the message says which.보내 드린 이메일에 회신하시거나 [email protected]으로 연락해 주십시오. 이렇게 거부된 환불은 생성되지 않았으므로 환불이 재개된 뒤 다시 요청해 주십시오. 결제 중지와 마찬가지로 범위는 계정 전체, 가맹점 한 곳, 또는 OutlinePay 전체일 수 있으며 메시지에 나옵니다.

Payment methods결제 수단

payment_methods is an allow-list of categories in OutlinePay's vocabulary, translated to the processor's methods at the boundary. Provide an array to offer exactly those. Omit it and you get ["card", "wallet"].payment_methods는 OutlinePay 용어로 정의된 결제 수단 분류의 허용 목록이며, 경계에서 처리사의 수단으로 변환됩니다. 배열을 지정하시면 그 분류만 노출됩니다. 생략하시면 ["card", "wallet"]이 적용됩니다.

Categories combine freely. Offer a capped bank rail beside cards and we ask the customer which they'll use before pricing, and fees stay null until they answer.분류는 자유롭게 조합하실 수 있습니다. 상한이 적용되는 은행 수단을 카드와 함께 제공하시면, 수수료를 확정하기 전에 저희가 고객께 사용하실 수단을 여쭙습니다. 답변 전까지 수수료는 null입니다.

Choosing bank_debitbank_debit 선택 기준
Offer it when you can wait a few business days to know you've been paid, and for amounts above $7,500 where it's the only bank option. Offering it turns off the instant bank option your processor would otherwise present on a card checkout, which settles like a card and is better if you fulfill on payment.결제 확인까지 영업일 기준 며칠을 기다리실 수 있을 때, 그리고 은행 결제가 유일한 수단인 7,500달러 초과 금액에 적합합니다. 이 수단을 제공하시면 카드 체크아웃에서 처리사가 대신 노출하던 즉시 은행 결제 옵션이 비활성화됩니다. 그 옵션은 카드와 동일하게 정산되므로 결제 즉시 상품을 발송하시는 경우에는 오히려 유리합니다.
bank_verificationbank_verification
How the customer proves the account is theirs. instant_or_delayed (the default) also lets them confirm two small deposits instead, which accepts the most customers but can leave a payment processing for a fortnight. instant answers immediately, and customers whose bank cannot be linked that way cannot pay by bank at all.고객이 해당 계좌가 본인 것임을 증명하는 방식입니다. 기본값인 instant_or_delayed는 소액 입금 2건을 확인하는 방식도 허용하므로 가장 많은 고객을 수용하지만, 결제가 2주가량 processing 상태에 머무를 수 있습니다. instant는 결과를 즉시 알려주지만, 계좌 연동이 불가능한 고객은 은행 결제를 아예 이용할 수 없습니다.
Live mode라이브 모드
A live merchant can only offer categories its processor has activated for it, which happens as onboarding completes. Offering one it cannot take is refused with 400 payment_method_not_enabled, naming the category and the ones the merchant can offer today. Test mode does not enforce this.라이브 가맹점은 결제 처리사가 활성화한 분류만 제공할 수 있으며, 활성화는 온보딩이 완료되면서 이루어집니다. 아직 받을 수 없는 분류를 제공하면 400 payment_method_not_enabled로 거부되며, 해당 분류와 가맹점이 현재 제공할 수 있는 분류가 함께 안내됩니다. 테스트 모드에서는 이 검사를 하지 않습니다.
Category카테고리 Covers (on Stripe)포함 수단 (Stripe) How it works작동 방식
card Cards, Apple Pay, Google Pay, Link카드, Apple Pay, Google Pay, Link Debit and credit cards. The card-based wallets (Apple Pay, Google Pay, Link) ride along automatically and can't be offered without cards.체크카드와 신용카드입니다. Apple Pay, Google Pay, Link처럼 카드 기반인 간편결제는 자동으로 함께 제공되며, 카드 없이는 단독으로 제공할 수 없습니다.
wallet Cash App, Amazon PayCash App, Amazon Pay Standalone wallets the customer pays from directly. (Apple Pay, Google Pay and Link are card-based, so they're part of card, not here.)고객이 직접 결제하는 독립형 간편결제입니다. (Apple Pay, Google Pay, Link는 카드 기반이므로 이곳이 아니라 card에 포함됩니다.)
bnpl Klarna, Affirm, AfterpayKlarna, Affirm, Afterpay Buy now, pay later. The customer splits the cost over time. You're paid in full up front.후불 결제입니다. 고객은 대금을 나누어 부담하고, 가맹점은 처음에 전액을 수령합니다.
bank_debit ACH Direct DebitACH 계좌 직불 Pull debit: the customer authorizes a pull from their US bank account. Settlement is delayed a few business days, so the payment sits in processing first, and it can fail after the customer has finished. Both our fee and yours are capped on it.출금 방식입니다. 고객이 미국 은행 계좌에서의 출금을 승인합니다. 정산이 영업일 기준 며칠 뒤에 이루어지므로 결제는 먼저 processing 상태에 머무르며, 고객이 결제를 마친 뒤에도 실패할 수 있습니다. OutlinePay 수수료와 파트너 수수료 모두 상한이 적용됩니다.
bank_transfer Bank transfer, virtual account (가상계좌)계좌이체 · 가상계좌 Push transfer: the customer is shown a virtual account number and sends the funds from their own bank. The payment sits in processing until the money arrives, and the same buyer keeps the same account number across payments. Requires customer.email when offered, and can't be offered on a payment link. Both our fee and yours are capped on it. US merchants only for now.입금 방식입니다. 고객에게 가상계좌 번호가 표시되고, 고객이 자신의 은행에서 자금을 보냅니다. 입금이 확인될 때까지 결제는 processing 상태에 머무르며, 같은 구매자는 결제할 때마다 같은 계좌번호를 사용합니다. 제공하려면 customer.email이 필요하고, 결제 링크에서는 제공할 수 없습니다. OutlinePay 수수료와 파트너 수수료 모두 상한이 적용됩니다. 현재는 미국 가맹점만 이용할 수 있습니다.

Localized pricing현지 통화 표시

A customer is charged in currency, wherever they are. localized_pricing on Create a payment and Create a payment link is the one exception, and it is off until you turn it on.고객은 어디에 있든 currency로 청구됩니다. 결제 생성과 결제 링크 생성의 localized_pricing이 유일한 예외이며, 켜시기 전까지는 꺼져 있습니다.

What the customer sees고객이 보는 것
With it on, the processor may show a customer outside the US the price in their own currency, beside the price in currency. The converted figure includes the processor's conversion fee, 2 to 4% with Stripe, and the customer pays it by choosing that option. Paying in currency costs them nothing extra from the processor.켜 두시면 결제 처리사가 미국 밖의 고객에게 currency 가격 옆에 고객 통화로 환산한 가격을 함께 보여줄 수 있습니다. 환산된 금액에는 처리사의 환전 수수료(Stripe 기준 2~4%)가 포함되어 있으며, 고객이 그 옵션을 선택하면 고객이 부담합니다. currency로 결제하면 처리사가 추가로 받는 비용은 없습니다.
What the merchant gets가맹점이 받는 것
amount in currency, either way. Fees are computed on that, and nothing in fees moves because the customer paid in another currency.어느 경우든 currency로 amount를 받습니다. 수수료는 그 금액을 기준으로 계산되며, 고객이 다른 통화로 결제했다고 해서 fees의 어떤 값도 달라지지 않습니다.
presentmentpresentment
When the customer took the converted price, the payment records it as presentment: the amount in their currency's minor unit, and the currency. It arrives with the other settlement facts on payment.updated, and it is null on every payment charged in currency. That is what the processor charged the card. What the customer's bank did after that is not visible to anyone.고객이 환산된 금액을 선택한 경우 결제 객체에 presentment로 기록됩니다. 고객 통화의 최소 단위 기준 금액과 통화입니다. 다른 정산 정보와 함께 payment.updated에 담겨 도착하며, currency로 청구된 결제에서는 모두 null입니다. 이 값은 처리사가 카드에 청구한 금액입니다. 그 이후 고객의 은행이 처리한 내용은 누구도 확인할 수 없습니다.
Refunds환불
You refund in currency as always. The processor returns the customer the exact amount they paid, in their currency, at the original rate.환불은 평소처럼 currency로 진행하시면 됩니다. 처리사는 고객이 실제로 결제한 금액을 고객 통화로, 원래 환율 그대로 돌려줍니다.

When each fee arrives각 수수료가 도착하는 시점

Six fields can only be read off the charge itself, so they are still null the moment a payment succeeds or fails: fees.processor, the processor's own cut, processor_payment_method, what actually settled, processor_reference, the processor's own id for the transaction, card, the card that settled it, presentment, what the customer paid when the price was localized, and funds_available_at, when the net enters the merchant's balance.여섯 필드는 결제 건 자체에서만 확인할 수 있으므로, 결제가 성공 또는 실패한 시점에는 아직 null입니다. 처리사가 취한 금액인 fees.processor, 실제로 정산된 수단인 processor_payment_method, 처리사 자신의 거래 식별자인 processor_reference, 결제에 사용된 카드 정보인 card, 가격이 현지 통화로 표시되었을 때 고객이 결제한 금액인 presentment, 그리고 정산 금액이 가맹점 잔액에 들어오는 날짜인 funds_available_at입니다.

payment.updatedpayment.updated
Fires a second or two after the outcome, carrying the same payment with the fields filled in. The status does not change, so read it as an amendment to the event before it. Usually one event covers every field. If the fee lags, the rest arrive first and a second event follows with the fee.결과 발생 후 1~2초 뒤에 발송되며, 해당 필드가 채워진 동일한 결제 객체를 담고 있습니다. status는 바뀌지 않으므로 직전 이벤트에 대한 정정으로 읽으시면 됩니다. 보통 한 번의 이벤트로 모든 필드가 전달되지만, 수수료 확인이 늦어지면 나머지가 먼저 도착하고 수수료를 담은 두 번째 이벤트가 뒤따릅니다.
Until it arrives도착 전까지
fees.total and merchant_net count an unread processor fee as zero, so both read high for those first seconds. On a $4,000 card that is $116.30 too much. Record net from payment.updated, not from payment.succeeded.fees.total과 merchant_net은 아직 확인되지 않은 처리사 수수료를 0으로 계산하므로, 처음 몇 초 동안 두 값이 실제보다 높게 표시됩니다. 4,000달러 카드 결제라면 116.30달러가 과다 계상됩니다. 정산 금액은 payment.succeeded가 아니라 payment.updated를 기준으로 기록하십시오.
Two fees take days며칠이 걸리는 두 수수료
fees.invoice and fees.fraud_screening are not on the charge. The processor takes them from the merchant's balance about a day later, as daily totals, and itemises them per payment only in a report it publishes 96 hours after that. So each lands about five days after the payment, on its own payment.updated. Null until then, and null is not zero. Both are live mode only: that report holds no test data, so in test mode they stay null for good. fees.pending is the field to read rather than the nulls themselves: it names the lines still to come.fees.invoice와 fees.fraud_screening은 결제 건 자체에 담기지 않습니다. 처리사는 하루 정도 뒤에 두 수수료를 일별 합계로 가맹점 잔액에서 차감하고, 결제별 내역은 그로부터 96시간이 지난 뒤에 리포트로 제공합니다. 따라서 각 수수료는 결제 시점보다 약 5일 뒤에 각각 별도의 payment.updated 이벤트로 도착합니다. 그전까지는 null이며, null은 0이 아닙니다. 두 필드 모두 라이브 모드에서만 제공됩니다. 해당 리포트에는 테스트 데이터가 없으므로 테스트 모드에서는 계속 null로 남습니다. null 값 자체가 아니라 fees.pending을 확인해 주십시오. 아직 도착하지 않은 항목이 여기에 표시됩니다.
Tax on those two두 수수료에 붙는 세금
The processor taxes its own invoicing and screening fees, at a rate set by the merchant's business address, so it differs by merchant. 0 means either that the fee is not taxed where the merchant is, or that this payment's share came to under half a cent, which is common on a screening fee of a few cents. The processor bills the tax as a daily total, so per-payment figures can add up to a cent or two under what it charged for the day. fees.tax carries it per fee, and each entry lands with the fee it belongs to. Add the two for what the merchant paid. fees.total and merchant_net already count it. Payment processing is not taxed, so fees.processor has no entry, and we add no tax to our fee or to yours.처리사는 자사의 인보이스 수수료와 사기 심사 수수료에 세금을 부과합니다. 세율은 가맹점의 사업장 주소를 기준으로 정해지므로 가맹점마다 다릅니다. 0은 두 가지를 뜻합니다. 해당 지역에서 그 수수료에 세금이 붙지 않거나, 이 결제 한 건에 해당하는 세액이 0.5센트 미만인 경우입니다. 수 센트 수준인 사기 심사 수수료에서는 후자가 흔합니다. 처리사는 세금을 일 단위 합계로 청구하므로, 결제별 금액을 모두 더하면 해당 일자에 실제로 청구된 금액보다 1~2센트 적을 수 있습니다. fees.tax가 수수료별 세금을 담고 있으며, 각 항목은 해당 수수료와 함께 도착합니다. 가맹점이 실제로 부담한 금액은 두 값을 더하시면 됩니다. fees.total과 merchant_net에는 이미 반영되어 있습니다. 결제 처리 수수료에는 세금이 붙지 않으므로 fees.processor에 대응하는 항목은 없으며, OutlinePay 수수료와 파트너 수수료에도 세금을 더하지 않습니다.
On a failure실패한 경우
A returned bank debit still costs the merchant a flat return charge, so fees.processor is filled in there too. Our fee and yours read zero because the processor hands them back, and merchant_net is negative by exactly the return charge. funds_available_at is the one field that never fills here. It only fills on a payment that collected money, so on a failure it stays null for good rather than arriving later.반환된 은행 출금에도 반환 건당 정액 수수료가 발생하므로 실패한 결제에도 fees.processor가 채워집니다. OutlinePay 수수료와 파트너 수수료는 처리사가 반환하므로 0으로 표시되며, merchant_net은 정확히 그 반환 수수료만큼 음수가 됩니다. funds_available_at은 실패한 결제에서 채워지지 않는 유일한 필드입니다. 금액이 실제로 회수된 결제에서만 채워지므로, 실패한 경우에는 나중에 도착하지 않고 계속 null로 남습니다.
If it never comes도착하지 않는 경우
A fee we cannot read is left null rather than guessed at zero, and a later reconciliation fills it in and emits then. Nothing else about the payment waits on it.확인할 수 없는 수수료는 0으로 추정하지 않고 null로 남겨 두며, 이후 대조 작업에서 값을 채우고 그 시점에 이벤트를 발송합니다. 결제의 다른 어떤 처리도 이 값을 기다리지 않습니다.

A dispute does not un-settle a payment분쟁은 결제 상태를 되돌리지 않습니다

A disputed payment's status stays succeeded. Whether the money stayed is answered by the dispute, not the status.분쟁이 발생한 결제도 status는 succeeded로 유지됩니다. 대금이 남아 있는지는 status가 아니라 분쟁 객체가 알려줍니다.

What it takes back회수되는 금액
disputes[].amount_withheld is how much of the payment the processor is holding, counted from the moment the dispute opens rather than when it closes. disputes[].fee is what it charged to handle the dispute, a flat $15 on Stripe. fees.total and merchant_net both account for the pair, which is why merchant_net goes negative on a payment that was lost.disputes[].amount_withheld는 처리사가 보류 중인 금액이며, 분쟁이 종료된 시점이 아니라 개시된 시점부터 계산됩니다. disputes[].fee는 분쟁 처리 대가로 청구된 금액이며 Stripe에서는 정액 15달러입니다. fees.total과 merchant_net은 두 값을 모두 반영하므로, 패소한 결제의 merchant_net은 음수가 됩니다.
Winning is not free승소해도 비용은 남습니다
The amount comes back and the fee does not: amount_withheld returns to 0 and fee stays.금액은 반환되지만 수수료는 반환되지 않습니다. amount_withheld는 0으로 돌아가고 fee는 그대로 유지됩니다.
No refund while it is held보류 중에는 환불 불가
amount_refundable reads 0 whenever amount_withheld is above zero. The processor refuses a refund on a charged-back payment whether the dispute is still open or already lost. Winning makes the payment refundable again.amount_withheld가 0보다 크면 amount_refundable은 0으로 표시됩니다. 분쟁이 진행 중이든 이미 패소했든, 처리사는 회수된 결제에 대한 환불을 거부합니다. 승소하면 해당 결제는 다시 환불 가능해집니다.
Fees are still charged수수료는 그대로 청구됩니다
Our fee and yours are both kept, as on a refund. Your earnings on the payment are unchanged.OutlinePay 수수료와 파트너 수수료는 환불의 경우와 동일하게 모두 유지됩니다. 해당 결제에서 발생한 파트너 수익은 변하지 않습니다.

Conventions규약

Events & webhooks이벤트와 웹훅

Webhook delivery웹훅 전달

Events are POSTed to every active webhook endpoint, signed with the OutlinePay-Signature header. Each event carries the object as it stood at that moment. Delivery is at-least-once with no promised order.이벤트는 활성 상태인 모든 웹훅 엔드포인트로 POST 전달되며, OutlinePay-Signature 헤더로 서명됩니다. 각 이벤트는 그 시점의 객체 전체를 담고 있습니다. 전달은 최소 1회(at-least-once) 보장이고 순서는 보장되지 않습니다.

What counts as delivered전달 완료의 기준
Any 2xx response within 10 seconds. Return it before doing slow work: a handler that processes first and answers second gets retried for running long, and then processes the same event twice.10초 이내의 2xx 응답입니다. 느린 작업은 응답을 반환하신 뒤에 처리해 주십시오. 처리를 먼저 하고 응답을 나중에 하는 핸들러는 시간 초과로 재시도 대상이 되어 같은 이벤트를 두 번 처리하게 됩니다.
Retries재시도
A failed delivery is retried up to 8 times over roughly 90 minutes, with growing gaps. After the last attempt we stop delivering that event to that endpoint.실패한 전달은 간격을 늘려 가며 약 90분에 걸쳐 최대 8회 재시도합니다. 마지막 시도 이후에는 해당 이벤트를 그 엔드포인트로 더 이상 전달하지 않습니다.
Duplicates중복 전달
Retries mean the same event can arrive twice. Record the event ids you have handled and skip repeats.재시도 때문에 같은 이벤트가 두 번 도착할 수 있습니다. 처리하신 이벤트 id를 기록해 두시고, 중복은 건너뛰어 주십시오.
No delivery order전달 순서 없음
Two events about the same object can arrive out of order: a refund event, then its payment.succeeded. Every event is self-sufficient, so handle each on its own facts. Do not return an error to force redelivery in order, that only spends the retries. If you need the object's latest state, use its Retrieve endpoint.같은 객체에 대한 두 이벤트가 순서가 뒤바뀌어 도착할 수 있습니다. 환불 이벤트가 먼저 오고, 해당 payment.succeeded가 나중에 올 수도 있습니다. 모든 이벤트는 그 자체로 완결적이므로 각 이벤트는 담긴 사실만으로 처리해 주십시오. 순서를 맞춰 다시 받으려고 오류를 반환하지 마십시오. 재시도만 소모됩니다. 객체의 최신 상태가 필요하시면 해당 객체의 조회 엔드포인트를 사용해 주십시오.
Missed events놓친 이벤트
Nothing is redelivered after the retries run out. List events is the catch-up path: every event stays readable there, newest first in emission order, so fetch what you missed and process it as though it had been delivered.재시도가 모두 소진된 뒤에는 자동으로 다시 전달되지 않습니다. 이벤트 목록 조회가 보완 경로입니다. 모든 이벤트는 그곳에서 발행 순서 기준 최신순으로 계속 조회하실 수 있으므로, 놓치신 이벤트를 가져와 전달받은 것처럼 처리해 주십시오.
Checking an event you received수신한 이벤트 확인
Any event can be fetched again by its id: Retrieve an event returns the same envelope.수신하신 이벤트는 id로 언제든 다시 조회하실 수 있습니다. 이벤트 조회가 같은 봉투를 반환합니다.
Replay protection재생 공격 방지
The signature's timestamp bounds how long a captured delivery stays valid. Reject a timestamp older than a few minutes, as the verification sample in the Quickstart does. It marks when the delivery attempt was sent, not when the event was created, so late retries still verify.서명의 타임스탬프는 탈취된 전달 건이 유효한 시간을 제한합니다. 시작하기 가이드의 검증 예시처럼 몇 분 이상 지난 타임스탬프는 거부해 주십시오. 타임스탬프는 이벤트 생성 시각이 아니라 해당 전달 시도의 발송 시각이므로, 늦은 재시도도 정상적으로 검증됩니다.

Object객체

The Merchant objectMerchant 객체

The businesses you accept payments for. A merchant becomes chargeable in three steps, in this order: create it, attach a processor to open its account, then have the merchant finish onboarding in an embedded component on your page. Charges are refused until the third step is done.귀사가 대신 결제를 받는 사업자입니다. 가맹점은 세 단계를 순서대로 거쳐야 결제를 받을 수 있습니다. 가맹점을 생성하고, 결제 처리사를 연결해 계정을 개설한 뒤, 귀사의 페이지에 삽입된 임베드 컴포넌트에서 가맹점이 온보딩을 완료해야 합니다. 세 번째 단계가 끝나기 전까지 결제는 거부됩니다.

Field필드 Type타입 Description설명
id string
object string

The literal string merchant.고정 문자열 merchant입니다.
name string
email string
status enum

Where the merchant stands with its processors: the field to read for whether it can charge today.가맹점이 결제 처리사와의 관계에서 어느 단계에 있는지, 즉 오늘 결제를 받을 수 있는지를 확인하는 필드입니다.

created: no processor has verified the merchant yet. This one value covers both a merchant that has not started onboarding and one whose submission is still under review. To tell those apart, read processors[].onboarding_completed.created: 아직 어떤 결제 처리사도 가맹점을 검증하지 않았습니다. 온보딩을 시작하지 않은 가맹점과 제출 후 심사 중인 가맹점을 모두 포함하는 값이므로, 둘을 구분하시려면 processors[].onboarding_completed를 읽어 주십시오.

active: a processor has verified the merchant and it can accept payments.active: 결제 처리사가 가맹점을 검증했으며 결제를 받을 수 있습니다.

restricted: a processor verified the merchant earlier but has since limited the account, usually because it now wants more information. Only the merchant can clear it, by answering the processor in the embedded components. A merchant that was never verified stays created, and processors[].verified never returns to false, so restricted is the only signal that a merchant which used to be chargeable no longer is.restricted: 결제 처리사가 과거에 가맹점을 검증했지만 이후 계정을 제한한 상태이며, 대개 추가 정보를 요구하는 경우입니다. 임베드 컴포넌트에서 처리사의 요청에 답하는 방식으로 가맹점만 해제할 수 있습니다. 한 번도 검증되지 않은 가맹점은 created로 유지되고 processors[].verified는 false로 되돌아가지 않으므로, 결제를 받을 수 있었던 가맹점이 더 이상 받을 수 없게 되었다는 신호는 restricted뿐입니다.

The API does not carry the reason for a restriction. The processor delivers it to the merchant in the notifications component, which is also the only place the merchant can answer it. So when you see restricted, put the merchant in front of notifications and account_management (see Create an account session). We emit merchant.updated when the status returns to active.제한 사유는 API로 전달되지 않습니다. 결제 처리사가 notifications 컴포넌트를 통해 가맹점에 직접 전달하며, 가맹점이 답할 수 있는 곳도 그곳뿐입니다. 따라서 restricted가 보이면 가맹점에게 notifications와 account_management 컴포넌트를 보여 주십시오(계정 세션 생성 참고). 상태가 active로 돌아오면 merchant.updated 이벤트를 발송합니다.

One of다음 중 하나
mode enum

The world this object lives in, test (sandbox) or live. Matches your API key's prefix (olp_sk_test_ / olp_sk_live_).이 객체가 속한 환경으로, test(샌드박스) 또는 live입니다. API 키의 접두사(olp_sk_test_ / olp_sk_live_)와 일치합니다.

One of다음 중 하나
country string

The merchant's legal-entity country, ISO 3166-1 alpha-2. Where the business is registered, not where its customers are. US today. Other countries are available on request.가맹점 법인의 국가이며 ISO 3166-1 alpha-2 코드입니다. 고객이 있는 곳이 아니라 사업자가 등록된 곳입니다. 현재는 US만 지원하며, 다른 국가는 요청 시 지원할 수 있습니다.
locale string

The language this merchant's onboarding renders in, or null if none was given (which onboards in English).이 가맹점의 온보딩이 렌더링되는 언어입니다. 지정하지 않으셨다면 null이며, 영어로 온보딩됩니다. nullable
entity_type enum

The legal entity type, if any.법적 실체 유형입니다(있는 경우). nullable

One of다음 중 하나
default_processor string

The rail a charge uses when the request names none. Null until the first processor is attached, which becomes the default. It never changes on its own after that.요청에 결제 처리사를 지정하지 않았을 때 결제가 사용하는 경로입니다. 첫 처리사를 연결하기 전까지는 null이며, 연결된 처리사가 기본값이 됩니다. 이후 저절로 바뀌지 않습니다. nullable
business object

Commercial details about the merchant's business. Fields marked merchant-owned are the merchant's to edit once they have onboarded, so they only ever travel inward.가맹점 사업체에 대한 상업 정보입니다. merchant-owned로 표시된 필드는 온보딩을 마친 가맹점만 수정할 수 있으므로 안쪽 방향으로만 이동합니다.

What you supplied at creation, updated when the merchant edits its details at the processor, so it can change without a call from you. Only business-level data is kept. Representative details are forwarded to the processor and never stored, so they are never returned here.생성 시 제공하신 값이며, 가맹점이 처리사에서 정보를 수정하면 갱신되므로 귀사의 호출 없이도 바뀔 수 있습니다. 사업체 수준의 데이터만 보관합니다. 대표자 정보는 처리사로 전달만 하고 저장하지 않으므로 이곳에 반환되지 않습니다. nullable
business.legal_name string

Registered legal name, if it differs from name.등록된 법적 상호입니다. name과 다른 경우에 보내 주십시오.
business.structure enum

The merchant's legal structure, in OutlinePay's processor-agnostic vocabulary, translated to your processor's own value. Applies to a company. An individual has none. These map to, in order: sole_proprietorship, single_member_llc, multi_member_llc, private_corporation, private_partnership.OutlinePay의 처리사 독립 용어로 표현한 가맹점의 법적 형태이며, 처리사의 값으로 변환해 전달합니다. 법인에만 적용됩니다. 개인에게는 없습니다. 순서대로 sole_proprietorship, single_member_llc, multi_member_llc, private_corporation, private_partnership에 대응합니다.

One of다음 중 하나
business.phone
merchant-owned 		string

Business phone. Use E.164: '+', the country code, then the subscriber number, e.g. +12125550123 (US) or +821012345678 (KR). A phone no processor could parse is refused as a 400 invalid_request naming this field.사업자 전화번호입니다. E.164 형식('+', 국가 코드, 가입자 번호 순)을 사용해 주십시오. 예: +12125550123(미국), +821012345678(한국). 어떤 처리사도 해석할 수 없는 전화번호는 이 필드를 지목한 400 invalid_request로 거부됩니다.
business.url string

Public website: a full http(s) URL with a domain name, e.g. https://hanui.example. The processor additionally refuses placeholder and shared domains (example.com and the like) when it is attached.공개 웹사이트입니다. 도메인 이름을 포함한 완전한 http(s) URL이어야 합니다. 예: https://hanui.example. 자리표시용·공용 도메인(example.com 등)은 처리사 연결 시점에 처리사가 추가로 거부합니다.
business.product_description
merchant-owned 		string

One or two sentences on what the merchant sells.가맹점이 판매하는 상품에 대한 한두 문장의 설명입니다.
business.industry_code
merchant-owned 		string

Four-digit merchant category code (MCC) classifying what the business sells: the card networks' ISO 18245 standard, not ours. Common examples: 5399 general merchandise, 5812 restaurants, 5691 clothing, 5734 software. Omit it and the processor infers one from the website and product description. We accept the codes listed at https://outlinepay.com/docs/mccs and refuse any other value naming this field.사업체가 판매하는 품목을 분류하는 4자리 업종 코드(MCC)로, OutlinePay가 아니라 카드 네트워크의 ISO 18245 표준입니다. 흔한 예: 5399 종합 소매, 5812 음식점, 5691 의류, 5734 소프트웨어. 생략하시면 처리사가 웹사이트와 상품 설명으로 추정합니다. 지원 코드 목록 (https://outlinepay.com/docs/mccs)의 코드를 받으며, 그 외의 값은 이 필드를 지목해 거부됩니다.
business.statement_descriptor
merchant-owned 		string

What buyers see on their card statement. 5 to 22 characters, at least one Latin letter, no angle brackets. Keep it recognisable, or it drives chargebacks.구매자의 카드 명세서에 표시되는 문구입니다. 5~22자이고, 라틴 문자를 하나 이상 포함하며, 꺾쇠괄호는 쓸 수 없습니다. 알아보기 쉽게 정하지 않으면 지불 거절의 원인이 됩니다.
business.address object
business.address.line1 string
business.address.line2 string
business.address.city string
business.address.state string

Two-letter state or province code. For a US address, the USPS code. The processor cannot serve US insular areas (GU, VI, AS, MP).두 글자 주/도 코드입니다. 미국 주소는 USPS 코드를 사용하며, 미국 도서 지역(GU, VI, AS, MP)은 결제 처리사가 지원하지 않습니다.
business.address.postal_code string

Postal code. For a US address, 5 digits or ZIP+4, e.g. 19104 or 19104-2617.우편번호입니다. 미국 주소는 5자리 또는 ZIP+4 형식입니다. 예: 19104, 19104-2617.
business.address.country string

Two-letter ISO country code, required whenever an address is sent. This is the country of *this address*: a business address must be in the merchant's own country (the top-level country on the merchant), while a representative's home address may be anywhere.두 글자 ISO 국가 코드로, 주소를 보내실 때는 필수입니다. 이는 *이 주소*의 국가입니다. 사업장 주소는 가맹점 자신의 국가(가맹점의 최상위 country)에 있어야 하며, 대표자의 자택 주소는 어느 국가든 가능합니다.
metadata object

Your own key/value pairs, for correlating this object back to your records. We never interpret the contents: they are stored, returned on every read, and carried on every event this object emits. A payment's, refund's or payment link's is also forwarded to the processor. A merchant's is not. At most 50 pairs, keys up to 40 characters, values up to 500. Values are stored as strings. Keys beginning outlinepay_, plus outline_fee and partner_fee, are reserved by OutlinePay and rejected. Never put secrets here.이 객체를 귀사의 기록과 연결하기 위한 자체 키/값 쌍입니다. OutlinePay는 내용을 해석하지 않습니다. 저장되고, 모든 조회에 반환되며, 이 객체가 발행하는 모든 이벤트에 실립니다. 결제, 환불, 결제 링크의 메타데이터는 결제 처리사에도 전달되며, 가맹점의 메타데이터는 전달되지 않습니다. 최대 50쌍, 키는 40자, 값은 500자까지이며 문자열로 저장됩니다. outlinepay_로 시작하는 키와 outline_fee, partner_fee는 OutlinePay가 예약하고 있어 거부됩니다. 비밀 정보는 절대 넣지 마십시오.
processors array<object>
processors[].processor string
processors[].account_id string

The processor's own account identifier (for Stripe, the connected account id, e.g. "acct_1AbC..."). Null in the brief window before the account is opened.결제 처리사 자체의 계정 식별자입니다(Stripe의 경우 연결 계정 id, 예: "acct_1AbC..."). 계정이 개설되기 전의 짧은 시간 동안은 null입니다. nullable
processors[].onboarding_completed boolean

True once the merchant has submitted its details to the processor. It says the merchant did its part, not that the processor accepted them, which is what verified says. While either is false, requirements says what is still outstanding and whose move it is. It never returns to false once set.가맹점이 결제 처리사에 정보를 제출하면 true가 됩니다. 가맹점이 할 일을 마쳤다는 뜻이지 처리사가 승인했다는 뜻은 아니며, 승인 여부는 verified가 알려줍니다. 둘 중 하나라도 false인 동안에는 requirements가 무엇이 남아 있고 다음 차례가 누구인지 알려줍니다. 한 번 true가 되면 false로 되돌아가지 않습니다.
processors[].representative_prefilled boolean

True once the representative supplied at attach reached the processor. False when none was supplied, or when it was rejected, in which case Attach a processor accepts the corrected one. A delivery flag only: the representative itself is forward-only and never returned.처리사 연결 시 제공한 representative가 처리사에 전달되면 true가 됩니다. 제공하지 않았거나 거부된 경우 false이며, 거부된 경우 Attach a processor가 수정한 representative를 다시 받습니다. 전달 여부만 나타내는 플래그입니다. representative 자체는 전달 후 폐기되며 응답으로 반환되지 않습니다.
processors[].requirements object

What the merchant still owes this processor, or null once it owes nothing.가맹점이 이 결제 처리사에 아직 제출해야 하는 항목이며, 남은 것이 없으면 null입니다. nullable
processors[].requirements.status enum

How urgent the strictest outstanding item is. overdue is holding the account back now, due keeps it working, upcoming is wanted once the merchant's volume passes the processor's thresholds.남은 항목 중 가장 급한 것의 시급도입니다. overdue는 지금 계정을 막고 있고, due는 계정을 계속 사용하려면 필요하며, upcoming은 가맹점의 거래액이 처리사의 기준을 넘으면 필요합니다.

One of다음 중 하나
processors[].requirements.blocks_charges boolean

True when the merchant cannot take a payment until something here is resolved.여기 있는 항목이 해결되기 전까지 가맹점이 결제를 받을 수 없으면 true입니다.
processors[].requirements.blocks_payouts boolean

True when the merchant cannot be paid out until something here is resolved.여기 있는 항목이 해결되기 전까지 가맹점이 정산을 받을 수 없으면 true입니다.
processors[].requirements.awaiting enum

Whose move is next. merchant means the account session and onboarding component will collect what is missing. processor means it has what it needs and is reviewing, so there is nothing to do but wait.다음 차례가 누구인지 나타냅니다. merchant는 계정 세션과 온보딩 컴포넌트로 부족한 항목을 수집하면 된다는 뜻입니다. processor는 처리사가 필요한 것을 모두 받아 심사 중이므로 기다리는 것 외에 할 일이 없다는 뜻입니다.

One of다음 중 하나
processors[].requirements.refreshed_at string

When we last read this from the processor, or when the account was opened there if we have not read it since.이 정보를 결제 처리사에서 마지막으로 읽어온 시각이며, 계정 개설 이후 아직 읽어온 적이 없다면 처리사에 계정이 개설된 시각입니다.
processors[].requirements.outstanding array<object>

One entry per thing the merchant has to do, the ones blocking charges first. Can be empty while the rest of this object is populated: the processor sometimes restricts an account before it says which fields it wants, and an empty list is not the same answer as a null requirements.가맹점이 해야 할 일마다 항목 하나씩이며, 결제를 막는 항목이 먼저 옵니다. 이 객체의 나머지 값이 채워진 상태에서도 비어 있을 수 있습니다. 결제 처리사가 필요한 필드를 알려주기 전에 계정을 먼저 제한하는 경우가 있기 때문이며, 빈 배열은 requirements가 null인 것과 다른 답입니다.
processors[].requirements.outstanding[].code enum

What the merchant has to do, in OutlinePay's vocabulary: accept the processor's agreement, supply the representative's identity, add a payout account, or correct the business category or details. other means the processor asked for something we have no word for yet, and processor_items is then the only description of it.가맹점이 해야 할 일을 OutlinePay의 용어로 나타냅니다. 결제 처리사의 약관 동의, 대표자 신원 제출, 정산 계좌 등록, 업종이나 사업자 정보 수정 중 하나입니다. other는 처리사가 요구한 항목에 대응하는 용어가 아직 없다는 뜻이며, 이 경우 processor_items가 그 항목을 설명하는 유일한 단서입니다.

One of다음 중 하나
processors[].requirements.outstanding[].blocks array<string>

What this item holds up. A group's value covers every item in it, so an item blocking charges and another blocking payouts give a group that lists both. For the exact answer read blocks_charges and blocks_payouts on the object above.이 항목이 막고 있는 것입니다. 그룹의 값은 그룹에 속한 모든 항목을 합친 것이므로, 결제를 막는 항목과 정산을 막는 항목이 같은 그룹에 있으면 둘 다 표시됩니다. 정확한 답이 필요하면 상위 객체의 blocks_charges와 blocks_payouts를 읽어 주십시오.
processors[].requirements.outstanding[].processor_items array<string>

The processor's own names for the fields behind this item, verbatim. Useful for telling a merchant precisely what failed, and outside our compatibility contract like every processor_ field.이 항목에 해당하는 필드를 결제 처리사가 부르는 이름 그대로입니다. 가맹점에게 정확히 무엇이 부족한지 전달할 때 유용하며, 다른 모든 processor_ 필드와 마찬가지로 호환성 보장 대상이 아닙니다.
processors[].verified boolean

True once the processor has accepted the merchant and will take charges for it. Until it is true, creating a payment or a payment link is refused with 409 merchant_not_onboarded, whatever onboarding_completed says. It turns true at the same moment the merchant's status becomes active, and a merchant.updated event is emitted then. It never returns to false. Whether the merchant can charge right now is status, which is where a later restriction shows up.결제 처리사가 가맹점을 승인해 결제를 받아 주기 시작하면 true가 됩니다. true가 되기 전까지는 onboarding_completed와 무관하게 결제 생성과 결제 링크 생성이 409 merchant_not_onboarded로 거부됩니다. 가맹점의 status가 active가 되는 순간 함께 true가 되고, 그때 merchant.updated 이벤트가 발송됩니다. false로 되돌아가지 않습니다. 지금 결제할 수 있는지는 status가 알려주며, 이후의 제한도 그곳에 반영됩니다.
terms_acceptance object

The merchant's acceptance of the OutlinePay merchant terms, or null if they have not accepted yet. Read-only. The merchant agrees on the terms screen the onboarding component shows ahead of the processor's form, we record it, and merchant.updated announces the change. One acceptance covers every processor. A merchant without one cannot take payments (409 merchant_terms_not_accepted), except merchants created before 2026-08-16, who are exempt until they next pass through onboarding.가맹점의 OutlinePay 가맹점 약관 동의 내역이며, 아직 동의하지 않았다면 null입니다. 읽기 전용입니다. 가맹점이 온보딩 컴포넌트가 결제 처리사의 양식에 앞서 보여주는 약관 화면에서 동의하면 당사가 기록하고, merchant.updated 이벤트로 변경을 알려드립니다. 한 번의 동의가 모든 결제 처리사에 적용됩니다. 동의 내역이 없는 가맹점은 결제를 받을 수 없으며(409 merchant_terms_not_accepted), 2026-08-16 이전에 생성된 가맹점은 다음 온보딩을 거치기 전까지 예외입니다. nullable
terms_acceptance.version string

The terms version accepted.동의한 약관 버전입니다.
terms_acceptance.accepted_at string
created_at string
The Merchant objectMerchant 객체 
{
  "id": "mrc_9f2c8bAaZ1kQ",
  "object": "merchant",
  "name": "Acme Trading Co.",
  "email": "[email protected]",
  "status": "active",
  "mode": "test",
  "entity_type": "company",
  "business": {
    "legal_name": "Acme Trading Co. LLC",
    "structure": "llc",
    "phone": "+12125550123",
    "url": "https://acme.example",
    "product_description": "Imported kitchenware and small appliances.",
    "industry_code": "5722",
    "statement_descriptor": "ACME TRADING",
    "address": {
      "line1": "1600 Market St",
      "city": "Philadelphia",
      "state": "PA",
      "postal_code": "19103",
      "country": "US"
    }
  },
  "metadata": {
    "shop_id": "shop-4821"
  },
  "processors": [
    {
      "processor": "stripe",
      "account_id": "acct_1AbCdEfGhIjKlMnO",
      "onboarding_completed": true,
      "verified": true,
      "representative_prefilled": true
    }
  ],
  "created_at": "2026-07-21T12:00:00Z"
}

POST /v1/merchants

Create a merchant가맹점 생성

Creates a merchant and returns it with an empty processors list. Opening the payment-processor account is a separate step, Attach a processor.가맹점을 생성하고 processors가 빈 목록인 상태로 반환합니다. 결제 처리사 계정 개설은 결제 처리사 연결이라는 별도 단계입니다.

Prefill사전 입력
business is commercial detail you already hold. We store it and hand it to the processor later so onboarding stops asking the merchant for it. All of it is returned on the merchant.business는 귀사가 이미 보유하고 계신 사업 정보입니다. OutlinePay가 저장해 두었다가 이후 결제 처리사에 전달하므로 온보딩에서 가맹점에 다시 묻지 않습니다. 모든 값은 가맹점 객체로 반환됩니다.
Not accepted here이곳에서 받지 않는 항목
The forward-only tax_id and representative. You supply those when you attach a processor, because we never store them.전달 전용인 tax_id와 representative입니다. 이 값들은 저장하지 않으므로, 결제 처리사를 연결하실 때 전달하십시오.
Accuracy정확성에 대한 책임
The merchant, not you, confirms to the processor that these details are true, and every value you send stays editable during onboarding. Tell them which values came from you so they can check them.이 정보가 사실임을 결제 처리사에 확인하는 주체는 귀사가 아니라 가맹점이며, 귀사가 전달한 모든 값은 온보딩 중에 계속 수정할 수 있습니다. 가맹점이 확인할 수 있도록 어떤 값이 귀사가 제공한 것인지 알려 주십시오.

Conventions규약 Merchant-owned fields가맹점 소유 필드

Emits이벤트 발행 merchant.created

Request body요청 본문

Field필드 Type타입 Description설명
name
required 		string
email
required 		string
country
required 		string

The merchant's legal-entity country, ISO 3166-1 alpha-2. Where the business is registered, not where its customers are. Required, and never inferred, because it decides the onboarding requirements. US is the only country enabled by default. A merchant created with a country that is not yet enabled is accepted here and then refused when you attach a processor. Other countries are available on request, see https://outlinepay.com/docs/countries.가맹점 법인의 국가이며 ISO 3166-1 alpha-2 코드입니다. 고객이 있는 곳이 아니라 사업자가 등록된 곳입니다. 온보딩 요건을 결정하므로 필수이며 추정하지 않습니다. 기본으로 활성화된 국가는 US뿐입니다. 아직 활성화되지 않은 국가로 생성된 가맹점은 이 호출에서는 수락되지만 결제 처리사를 연결할 때 거부됩니다. 다른 국가는 요청 시 지원할 수 있습니다. https://outlinepay.com/docs/countries 를 참고하십시오.
locale
optional 		enum

The language this merchant reads. It decides what language their onboarding form is rendered in and what language the payment processor writes to them in afterwards, so send it if you know it. Optional: leave it out and the merchant is onboarded in English. en and ko are what we support today. Anything else is rejected, not downgraded to English. Tell us which ones you need and we will add them.이 가맹점이 읽는 언어입니다. 온보딩 양식이 렌더링되는 언어와 이후 결제 처리사가 가맹점에 보내는 안내의 언어를 결정하므로, 알고 계시다면 보내 주십시오. 선택 사항이며, 생략하시면 영어로 온보딩됩니다. 현재 지원 언어는 en과 ko입니다. 그 외의 값은 영어로 대체하지 않고 거부합니다. 필요하신 언어를 알려 주시면 추가하겠습니다.

One of다음 중 하나
entity_type
optional 		enum

Whether the merchant is a registered business or a person trading under their own name.가맹점이 등록된 사업체인지, 본인 명의로 거래하는 개인인지입니다.

One of다음 중 하나
business
optional 		object

Commercial details about the merchant's business. Fields marked merchant-owned are the merchant's to edit once they have onboarded, so they only ever travel inward.가맹점 사업체에 대한 상업 정보입니다. merchant-owned로 표시된 필드는 온보딩을 마친 가맹점만 수정할 수 있으므로 안쪽 방향으로만 이동합니다.

The details you already hold. Stored and returned on the merchant in full. The forward-only tax_id and representative are not accepted here: you supply them when you attach a processor.이미 보유하고 계신 정보입니다. 저장되어 가맹점 객체로 온전히 반환됩니다. 전달 전용인 tax_id와 representative는 여기서 받지 않으며, 결제 처리사를 연결하실 때 전달합니다.
business.legal_name
optional 		string

Registered legal name, if it differs from name.등록된 법적 상호입니다. name과 다른 경우에 보내 주십시오.
business.structure
optional 		enum

The merchant's legal structure, in OutlinePay's processor-agnostic vocabulary, translated to your processor's own value. Applies to a company. An individual has none. These map to, in order: sole_proprietorship, single_member_llc, multi_member_llc, private_corporation, private_partnership.OutlinePay의 처리사 독립 용어로 표현한 가맹점의 법적 형태이며, 처리사의 값으로 변환해 전달합니다. 법인에만 적용됩니다. 개인에게는 없습니다. 순서대로 sole_proprietorship, single_member_llc, multi_member_llc, private_corporation, private_partnership에 대응합니다.

One of다음 중 하나
business.phone
optional
merchant-owned 		string

Business phone. Use E.164: '+', the country code, then the subscriber number, e.g. +12125550123 (US) or +821012345678 (KR). A phone no processor could parse is refused as a 400 invalid_request naming this field.사업자 전화번호입니다. E.164 형식('+', 국가 코드, 가입자 번호 순)을 사용해 주십시오. 예: +12125550123(미국), +821012345678(한국). 어떤 처리사도 해석할 수 없는 전화번호는 이 필드를 지목한 400 invalid_request로 거부됩니다.
business.url
optional 		string

Public website: a full http(s) URL with a domain name, e.g. https://hanui.example. The processor additionally refuses placeholder and shared domains (example.com and the like) when it is attached.공개 웹사이트입니다. 도메인 이름을 포함한 완전한 http(s) URL이어야 합니다. 예: https://hanui.example. 자리표시용·공용 도메인(example.com 등)은 처리사 연결 시점에 처리사가 추가로 거부합니다.
business.product_description
optional
merchant-owned 		string

One or two sentences on what the merchant sells.가맹점이 판매하는 상품에 대한 한두 문장의 설명입니다.
business.industry_code
optional
merchant-owned 		string

Four-digit merchant category code (MCC) classifying what the business sells: the card networks' ISO 18245 standard, not ours. Common examples: 5399 general merchandise, 5812 restaurants, 5691 clothing, 5734 software. Omit it and the processor infers one from the website and product description. We accept the codes listed at https://outlinepay.com/docs/mccs and refuse any other value naming this field.사업체가 판매하는 품목을 분류하는 4자리 업종 코드(MCC)로, OutlinePay가 아니라 카드 네트워크의 ISO 18245 표준입니다. 흔한 예: 5399 종합 소매, 5812 음식점, 5691 의류, 5734 소프트웨어. 생략하시면 처리사가 웹사이트와 상품 설명으로 추정합니다. 지원 코드 목록 (https://outlinepay.com/docs/mccs)의 코드를 받으며, 그 외의 값은 이 필드를 지목해 거부됩니다.
business.statement_descriptor
optional
merchant-owned 		string

What buyers see on their card statement. 5 to 22 characters, at least one Latin letter, no angle brackets. Keep it recognisable, or it drives chargebacks.구매자의 카드 명세서에 표시되는 문구입니다. 5~22자이고, 라틴 문자를 하나 이상 포함하며, 꺾쇠괄호는 쓸 수 없습니다. 알아보기 쉽게 정하지 않으면 지불 거절의 원인이 됩니다.
business.address
optional 		object
business.address.line1
optional 		string
business.address.line2
optional 		string
business.address.city
optional 		string
business.address.state
optional 		string

Two-letter state or province code. For a US address, the USPS code. The processor cannot serve US insular areas (GU, VI, AS, MP).두 글자 주/도 코드입니다. 미국 주소는 USPS 코드를 사용하며, 미국 도서 지역(GU, VI, AS, MP)은 결제 처리사가 지원하지 않습니다.
business.address.postal_code
optional 		string

Postal code. For a US address, 5 digits or ZIP+4, e.g. 19104 or 19104-2617.우편번호입니다. 미국 주소는 5자리 또는 ZIP+4 형식입니다. 예: 19104, 19104-2617.
business.address.country
optional 		string

Two-letter ISO country code, required whenever an address is sent. This is the country of *this address*: a business address must be in the merchant's own country (the top-level country on the merchant), while a representative's home address may be anywhere.두 글자 ISO 국가 코드로, 주소를 보내실 때는 필수입니다. 이는 *이 주소*의 국가입니다. 사업장 주소는 가맹점 자신의 국가(가맹점의 최상위 country)에 있어야 하며, 대표자의 자택 주소는 어느 국가든 가능합니다.
metadata
optional 		object

Your own key/value pairs, for correlating this object back to your records. We never interpret the contents: they are stored, returned on every read, and carried on every event this object emits. A payment's, refund's or payment link's is also forwarded to the processor. A merchant's is not. At most 50 pairs, keys up to 40 characters, values up to 500. Values are stored as strings. Keys beginning outlinepay_, plus outline_fee and partner_fee, are reserved by OutlinePay and rejected. Never put secrets here.이 객체를 귀사의 기록과 연결하기 위한 자체 키/값 쌍입니다. OutlinePay는 내용을 해석하지 않습니다. 저장되고, 모든 조회에 반환되며, 이 객체가 발행하는 모든 이벤트에 실립니다. 결제, 환불, 결제 링크의 메타데이터는 결제 처리사에도 전달되며, 가맹점의 메타데이터는 전달되지 않습니다. 최대 50쌍, 키는 40자, 값은 500자까지이며 문자열로 저장됩니다. outlinepay_로 시작하는 키와 outline_fee, partner_fee는 OutlinePay가 예약하고 있어 거부됩니다. 비밀 정보는 절대 넣지 마십시오.

Your own key/value pairs, such as your id for this seller. Kept by OutlinePay and never sent to the processor.이 판매자에 대한 귀사의 id처럼, 귀사가 정의하는 키/값 쌍입니다. OutlinePay가 보관하며 결제 처리사에는 전달하지 않습니다.

Example request요청 예시

<?php
$ch = curl_init("https://api.outlinepay.com/v1/merchants");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer olp_sk_test_YOUR_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "name"        => "Acme Trading Co.",
        "email"       => "[email protected]",
        "country"     => "US",
        "entity_type" => "company",
        "business"    => [
            "legal_name"           => "Acme Trading Co. LLC",
            "structure"            => "llc",
            "phone"                => "+12125550123",
            "url"                  => "https://acme.example",
            "product_description"  => "Imported kitchenware and small appliances.",
            "industry_code"        => "5722",
            "statement_descriptor" => "ACME TRADING",
            "address"              => [
                "line1"       => "1600 Market St",
                "city"        => "Philadelphia",
                "state"       => "PA",
                "postal_code" => "19103",
                "country"     => "US",
            ],
        ],
        "metadata"    => [
            "shop_id" => "shop-4821",
        ],
    ]),
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Response응답

Returns a Merchant.Merchant 객체를 반환합니다.

Response응답 · 200 
{
  "id": "mrc_9f2c8bAaZ1kQ",
  "object": "merchant",
  "name": "Acme Trading Co.",
  "email": "[email protected]",
  "status": "created",
  "mode": "test",
  "entity_type": "company",
  "business": {
    "legal_name": "Acme Trading Co. LLC",
    "structure": "llc",
    "phone": "+12125550123",
    "url": "https://acme.example",
    "product_description": "Imported kitchenware and small appliances.",
    "industry_code": "5722",
    "statement_descriptor": "ACME TRADING",
    "address": {
      "line1": "1600 Market St",
      "city": "Philadelphia",
      "state": "PA",
      "postal_code": "19103",
      "country": "US"
    }
  },
  "metadata": {
    "shop_id": "shop-4821"
  },
  "processors": [],
  "created_at": "2026-07-21T12:00:00Z"
}

GET /v1/merchants

List merchants가맹점 목록 조회

Your merchants, newest first. Filter by status and creation time.귀사의 가맹점을 최신순으로 반환합니다. status와 생성 시각으로 필터링하실 수 있습니다.

Parameters파라미터

Parameter파라미터 In위치 Type타입 Description설명
status
optional 		query enum

Where the merchant stands with its processors: the field to read for whether it can charge today.가맹점이 결제 처리사와의 관계에서 어느 단계에 있는지, 즉 오늘 결제를 받을 수 있는지를 확인하는 필드입니다.

created: no processor has verified the merchant yet. This one value covers both a merchant that has not started onboarding and one whose submission is still under review. To tell those apart, read processors[].onboarding_completed.created: 아직 어떤 결제 처리사도 가맹점을 검증하지 않았습니다. 온보딩을 시작하지 않은 가맹점과 제출 후 심사 중인 가맹점을 모두 포함하는 값이므로, 둘을 구분하시려면 processors[].onboarding_completed를 읽어 주십시오.

active: a processor has verified the merchant and it can accept payments.active: 결제 처리사가 가맹점을 검증했으며 결제를 받을 수 있습니다.

restricted: a processor verified the merchant earlier but has since limited the account, usually because it now wants more information. Only the merchant can clear it, by answering the processor in the embedded components. A merchant that was never verified stays created, and processors[].verified never returns to false, so restricted is the only signal that a merchant which used to be chargeable no longer is.restricted: 결제 처리사가 과거에 가맹점을 검증했지만 이후 계정을 제한한 상태이며, 대개 추가 정보를 요구하는 경우입니다. 임베드 컴포넌트에서 처리사의 요청에 답하는 방식으로 가맹점만 해제할 수 있습니다. 한 번도 검증되지 않은 가맹점은 created로 유지되고 processors[].verified는 false로 되돌아가지 않으므로, 결제를 받을 수 있었던 가맹점이 더 이상 받을 수 없게 되었다는 신호는 restricted뿐입니다.

The API does not carry the reason for a restriction. The processor delivers it to the merchant in the notifications component, which is also the only place the merchant can answer it. So when you see restricted, put the merchant in front of notifications and account_management (see Create an account session). We emit merchant.updated when the status returns to active.제한 사유는 API로 전달되지 않습니다. 결제 처리사가 notifications 컴포넌트를 통해 가맹점에 직접 전달하며, 가맹점이 답할 수 있는 곳도 그곳뿐입니다. 따라서 restricted가 보이면 가맹점에게 notifications와 account_management 컴포넌트를 보여 주십시오(계정 세션 생성 참고). 상태가 active로 돌아오면 merchant.updated 이벤트를 발송합니다.

Only merchants in this state.이 상태의 가맹점만 반환합니다.

One of다음 중 하나
created_after
optional 		query string

Only records whose created_at is at or after this ISO 8601 timestamp or date. Inclusive.created_at이 이 ISO 8601 시각 또는 날짜 이후(같은 시각 포함)인 항목만 반환합니다.
created_before
optional 		query string

Only records whose created_at is before this ISO 8601 timestamp or date. Exclusive, so a month's created_before is the next month's created_after.created_at이 이 ISO 8601 시각 또는 날짜 이전인 항목만 반환합니다. 같은 시각은 제외되므로, 한 달의 created_before가 다음 달의 created_after가 됩니다.
limit
optional 		query integer

Page size, 1–100 (default 20).페이지 크기이며 1~100(기본값 20)입니다.
starting_after
optional 		query string

A resource id. Returns records after it (newest-first cursor).리소스 id이며, 그 이후의 레코드를 반환합니다(최신순 커서).

Example request요청 예시

<?php
$ch = curl_init("https://api.outlinepay.com/v1/merchants?created_after=2026-08-01T00:00:00Z&created_before=2026-09-01T00:00:00Z&limit=20");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer olp_sk_test_YOUR_KEY",
    ],
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Response응답

Returns a page of Merchant objects: { "data": [...], "has_more": bool }.Merchant 객체의 목록 페이지를 반환합니다: { "data": [...], "has_more": bool }.

GET /v1/merchants/{id}

Retrieve a merchant가맹점 조회

The authoritative merchant record, including per-processor onboarding/verification state.결제 처리사별 온보딩 및 인증 상태를 포함한 가맹점의 기준 정보입니다.

Parameters파라미터

Parameter파라미터 In위치 Type타입 Description설명
id
required 		path string

The merchant id.가맹점 id입니다.

Example request요청 예시

<?php
$ch = curl_init("https://api.outlinepay.com/v1/merchants/mrc_9f2c8bAaZ1kQ");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer olp_sk_test_YOUR_KEY",
    ],
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Response응답

Returns a Merchant.Merchant 객체를 반환합니다.

Response응답 · 200 
{
  "id": "mrc_9f2c8bAaZ1kQ",
  "object": "merchant",
  "name": "Acme Trading Co.",
  "email": "[email protected]",
  "status": "active",
  "mode": "test",
  "entity_type": "company",
  "business": {
    "legal_name": "Acme Trading Co. LLC",
    "structure": "llc",
    "phone": "+12125550123",
    "url": "https://acme.example",
    "product_description": "Imported kitchenware and small appliances.",
    "industry_code": "5722",
    "statement_descriptor": "ACME TRADING",
    "address": {
      "line1": "1600 Market St",
      "city": "Philadelphia",
      "state": "PA",
      "postal_code": "19103",
      "country": "US"
    }
  },
  "metadata": {
    "shop_id": "shop-4821"
  },
  "processors": [
    {
      "processor": "stripe",
      "account_id": "acct_1AbCdEfGhIjKlMnO",
      "onboarding_completed": true,
      "verified": true,
      "representative_prefilled": true
    }
  ],
  "created_at": "2026-07-21T12:00:00Z"
}

PATCH /v1/merchants/{id}

Update a merchant가맹점 수정

Updates the merchant's processor-agnostic business identity. Changes travel the other way too, with no call from you: when the merchant edits their details at the processor, we write them back here automatically.결제 처리사와 무관한 가맹점의 사업자 정보를 수정합니다. 반대 방향으로도 반영됩니다. 가맹점이 결제 처리사에서 정보를 수정하면 귀사의 별도 호출 없이 이곳에 자동으로 반영됩니다.

Merge semantics병합 방식
A field you omit is left unchanged, a field you send is set, and a field you send blank is cleared.생략하신 필드는 그대로 유지되고, 전달하신 필드는 해당 값으로 설정되며, 빈 값으로 전달하신 필드는 삭제됩니다.
Merchant-owned가맹점 소유 항목
product_description, industry_code, statement_descriptor and phone are editable here only until a processor is attached. From then on the merchant owns them: they are edited in the account-management component and reach us through the inbound sync instead.product_description, industry_code, statement_descriptor, phone은 결제 처리사를 연결하기 전까지만 이곳에서 수정할 수 있습니다. 연결 이후에는 가맹점이 소유하므로, 계정 관리 컴포넌트에서 수정되고 인바운드 동기화를 통해 OutlinePay로 전달됩니다.
Not accepted here이곳에서 받지 않는 항목
The forward-only tax_id and representative, which belong to the attach endpoint.전달 전용인 tax_id와 representative이며, 결제 처리사 연결 엔드포인트에 속합니다.
Propagation전파 방식
Stored here, then pushed to every attached processor account, matching fields best-effort: each processor receives the ones it models and anything it cannot model is still stored here, just not forwarded. Today legal_name, structure and address reach the processor only for a company, since an individual's identity is held as a person rather than a business.이곳에 저장한 뒤 연결된 모든 결제 처리사 계정에 최선 노력으로 전달합니다. 각 처리사는 자신이 다루는 항목만 수신하며, 처리사가 다루지 않는 항목도 이곳에는 저장되고 전달만 되지 않습니다. 현재 legal_name, structure, address는 법인인 경우에만 처리사로 전달됩니다. 개인 사업자의 신원은 사업체가 아니라 개인으로 관리되기 때문입니다.

Conventions규약 Merchant-owned fields가맹점 소유 필드

Emits이벤트 발행 merchant.updated

Parameters파라미터

Parameter파라미터 In위치 Type타입 Description설명
id
required 		path string

The merchant id.가맹점 id입니다.

Request body요청 본문

Field필드 Type타입 Description설명
entity_type
optional 		enum

Set-only. Sending it blank does not clear it.설정 전용입니다. 빈 값을 보내도 삭제되지 않습니다.

One of다음 중 하나
locale
optional 		enum

The language this merchant reads. Change it when you learn you had it wrong, or when the merchant asks: it was previously fixed at creation, and a merchant who signed up in the wrong language stayed in it.이 가맹점이 읽는 언어입니다. 잘못 알고 계셨음을 알게 되었거나 가맹점이 요청할 때 변경하십시오. 이전에는 생성 시 고정되어, 잘못된 언어로 가입한 가맹점이 그 언어에 계속 머물렀습니다.

Follows this endpoint's merge rule. Omit it and the language is left alone. Send en or ko to set it. Send it blank to clear it, which returns the merchant to being onboarded in English.이 엔드포인트의 병합 규칙을 따릅니다. 생략하시면 그대로 둡니다. en이나 ko를 보내시면 설정됩니다. 빈 값을 보내시면 삭제되어 영어 온보딩으로 돌아갑니다.

It takes effect on the next account session you create. Components already on screen keep the locale they were initialised with, so by default the merchant sees the change on their next page load. If you want it sooner, the embedded components can be re-translated in place without re-mounting: call stripeConnectInstance.update({locale}) with the locale from a freshly created account session. Nothing is sent to the processor when this changes, because the processor holds no copy of it.다음에 생성하시는 계정 세션부터 적용됩니다. 이미 화면에 있는 컴포넌트는 초기화 시점의 언어를 유지하므로, 기본적으로 가맹점은 다음 페이지 로드에서 변경을 보게 됩니다. 더 빨리 반영하시려면, 새로 생성한 계정 세션의 locale로 stripeConnectInstance.update({locale})을 호출하시면 다시 마운트하지 않고도 컴포넌트가 제자리에서 번역됩니다. 처리사는 이 값을 보관하지 않으므로 변경 시 처리사로 보내는 것은 없습니다. nullable

One of다음 중 하나
business
optional 		object

The business fields a partial update may touch.부분 수정으로 변경할 수 있는 사업 필드입니다.

The identity fields to set or clear.설정하거나 삭제할 신원 필드입니다.
business.legal_name
optional 		string

Registered legal name, if it differs from name.등록된 법적 상호입니다. name과 다른 경우에 보내 주십시오.
business.structure
optional 		enum

The merchant's legal structure, in OutlinePay's processor-agnostic vocabulary (company only). See MerchantBusiness for what each maps to.OutlinePay의 처리사 독립 용어로 표현한 가맹점의 법적 형태입니다(법인 전용). 각 값의 대응은 MerchantBusiness를 참고해 주십시오.

One of다음 중 하나
business.url
optional 		string

Public website: a full http(s) URL with a domain name, e.g. https://hanui.example. The processor additionally refuses placeholder and shared domains (example.com and the like) when it is attached.공개 웹사이트입니다. 도메인 이름을 포함한 완전한 http(s) URL이어야 합니다. 예: https://hanui.example. 자리표시용·공용 도메인(example.com 등)은 처리사 연결 시점에 처리사가 추가로 거부합니다.
business.address
optional 		object
business.address.line1
optional 		string
business.address.line2
optional 		string
business.address.city
optional 		string
business.address.state
optional 		string

Two-letter state or province code. For a US address, the USPS code. The processor cannot serve US insular areas (GU, VI, AS, MP).두 글자 주/도 코드입니다. 미국 주소는 USPS 코드를 사용하며, 미국 도서 지역(GU, VI, AS, MP)은 결제 처리사가 지원하지 않습니다.
business.address.postal_code
optional 		string

Postal code. For a US address, 5 digits or ZIP+4, e.g. 19104 or 19104-2617.우편번호입니다. 미국 주소는 5자리 또는 ZIP+4 형식입니다. 예: 19104, 19104-2617.
business.address.country
optional 		string

Two-letter ISO country code, required whenever an address is sent. This is the country of *this address*: a business address must be in the merchant's own country (the top-level country on the merchant), while a representative's home address may be anywhere.두 글자 ISO 국가 코드로, 주소를 보내실 때는 필수입니다. 이는 *이 주소*의 국가입니다. 사업장 주소는 가맹점 자신의 국가(가맹점의 최상위 country)에 있어야 하며, 대표자의 자택 주소는 어느 국가든 가능합니다.
business.phone
optional
merchant-owned 		string

Business phone. Use E.164: '+', the country code, then the subscriber number, e.g. +12125550123 (US) or +821012345678 (KR). A phone no processor could parse is refused as a 400 invalid_request naming this field.사업자 전화번호입니다. E.164 형식('+', 국가 코드, 가입자 번호 순)을 사용해 주십시오. 예: +12125550123(미국), +821012345678(한국). 어떤 처리사도 해석할 수 없는 전화번호는 이 필드를 지목한 400 invalid_request로 거부됩니다.
business.product_description
optional
merchant-owned 		string

One or two sentences on what the merchant sells.가맹점이 판매하는 상품에 대한 한두 문장의 설명입니다.
business.industry_code
optional
merchant-owned 		string

Four-digit merchant category code (MCC) classifying what the business sells: the card networks' ISO 18245 standard, not ours. Common examples: 5399 general merchandise, 5812 restaurants, 5691 clothing, 5734 software. Omit it and the processor infers one from the website and product description. We accept the codes listed at https://outlinepay.com/docs/mccs and refuse any other value naming this field.사업체가 판매하는 품목을 분류하는 4자리 업종 코드(MCC)로, OutlinePay가 아니라 카드 네트워크의 ISO 18245 표준입니다. 흔한 예: 5399 종합 소매, 5812 음식점, 5691 의류, 5734 소프트웨어. 생략하시면 처리사가 웹사이트와 상품 설명으로 추정합니다. 지원 코드 목록 (https://outlinepay.com/docs/mccs)의 코드를 받으며, 그 외의 값은 이 필드를 지목해 거부됩니다.
business.statement_descriptor
optional
merchant-owned 		string

What buyers see on their card statement. 5 to 22 characters, at least one Latin letter, no angle brackets. Keep it recognisable, or it drives chargebacks.구매자의 카드 명세서에 표시되는 문구입니다. 5~22자이고, 라틴 문자를 하나 이상 포함하며, 꺾쇠괄호는 쓸 수 없습니다. 알아보기 쉽게 정하지 않으면 지불 거절의 원인이 됩니다.
metadata
optional 		object

Your own key/value pairs, for correlating this object back to your records. We never interpret the contents: they are stored, returned on every read, and carried on every event this object emits. A payment's, refund's or payment link's is also forwarded to the processor. A merchant's is not. At most 50 pairs, keys up to 40 characters, values up to 500. Values are stored as strings. Keys beginning outlinepay_, plus outline_fee and partner_fee, are reserved by OutlinePay and rejected. Never put secrets here.이 객체를 귀사의 기록과 연결하기 위한 자체 키/값 쌍입니다. OutlinePay는 내용을 해석하지 않습니다. 저장되고, 모든 조회에 반환되며, 이 객체가 발행하는 모든 이벤트에 실립니다. 결제, 환불, 결제 링크의 메타데이터는 결제 처리사에도 전달되며, 가맹점의 메타데이터는 전달되지 않습니다. 최대 50쌍, 키는 40자, 값은 500자까지이며 문자열로 저장됩니다. outlinepay_로 시작하는 키와 outline_fee, partner_fee는 OutlinePay가 예약하고 있어 거부됩니다. 비밀 정보는 절대 넣지 마십시오.

Merged key by key under this endpoint's rule. Send a key with a value to set it, or blank to remove it. Keys you leave out are kept. Changing only metadata makes no call to the processor.이 엔드포인트의 병합 규칙에 따라 키 단위로 병합됩니다. 값과 함께 보내신 키는 설정되고, 빈 값으로 보내신 키는 삭제되며, 보내지 않으신 키는 그대로 유지됩니다. 메타데이터만 바꾸는 경우 결제 처리사를 호출하지 않습니다.

Example request요청 예시

<?php
$ch = curl_init("https://api.outlinepay.com/v1/merchants/mrc_9f2c8bAaZ1kQ");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => "PATCH",
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer olp_sk_test_YOUR_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "business" => [
            "url"        => "https://acme.example",
            "legal_name" => "Acme Trading Co. LLC",
        ],
    ]),
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Response응답

Returns a Merchant.Merchant 객체를 반환합니다.

Response응답 · 200 
{
  "id": "mrc_9f2c8bAaZ1kQ",
  "object": "merchant",
  "name": "Acme Trading Co.",
  "email": "[email protected]",
  "status": "active",
  "mode": "test",
  "entity_type": "company",
  "business": {
    "legal_name": "Acme Trading Co. LLC",
    "structure": "llc",
    "phone": "+12125550123",
    "url": "https://acme.example",
    "product_description": "Imported kitchenware and small appliances.",
    "industry_code": "5722",
    "statement_descriptor": "ACME TRADING",
    "address": {
      "line1": "1600 Market St",
      "city": "Philadelphia",
      "state": "PA",
      "postal_code": "19103",
      "country": "US"
    }
  },
  "metadata": {
    "shop_id": "shop-4821"
  },
  "processors": [
    {
      "processor": "stripe",
      "account_id": "acct_1AbCdEfGhIjKlMnO",
      "onboarding_completed": true,
      "verified": true,
      "representative_prefilled": true
    }
  ],
  "created_at": "2026-07-21T12:00:00Z"
}

POST /v1/merchants/{merchant_id}/processors

Attach a processor결제 처리사 연결

Opens the merchant's connected payment-processor account, the step that makes a merchant chargeable.가맹점의 결제 처리사 연결 계정을 개설하며, 이 단계를 거쳐야 가맹점이 결제를 받을 수 있습니다.

Forward-only identity전달 전용 신원 정보
This is where tax_id and the representative are supplied. We pass them to the processor and then discard them: never written down, never returned, so they cannot appear in a later GET, an event payload or a backup.tax_id와 representative를 전달하는 곳이 바로 이 단계입니다. 결제 처리사에 전달한 뒤 폐기하며, 기록하지도 반환하지도 않으므로 이후의 GET 응답이나 이벤트 페이로드, 백업에 나타날 수 없습니다.
Effect on onboarding온보딩에 미치는 효과
Combined with the business stored at creation, it takes a US company's onboarding from 15 outstanding requirements down to 4. The merchant is left with its bank account, the last four digits of the representative's national ID, and the terms of service.가맹점 생성 시 저장한 business와 함께 사용하면, 미국 법인의 온보딩 미충족 요건이 15개에서 4개로 줄어듭니다. 가맹점에는 은행 계좌, 대표자 주민등록번호 성격 식별자의 뒤 네 자리, 이용약관 동의만 남습니다.
What happens next이후 진행
The account is open but restricted, so this call does not make the merchant chargeable on its own: onboarding_completed and verified both come back false and status stays created. Create an account session next and render the onboarding component, which is where the processor collects what it still needs. Until that finishes, charges are refused with 409 merchant_not_onboarded.계정은 개설되었지만 제한된 상태이므로, 이 호출만으로 가맹점이 결제를 받을 수 있게 되지는 않습니다. onboarding_completed와 verified는 모두 false로 반환되고 status는 created로 유지됩니다. 다음으로 계정 세션을 생성해 온보딩 컴포넌트를 렌더링하시면, 결제 처리사가 아직 필요로 하는 항목을 그곳에서 수집합니다. 완료되기 전까지 결제는 409 merchant_not_onboarded로 거부됩니다.
If the representative is rejected대표자가 거부된 경우
For a company, opening the account and registering the representative are two steps at the processor, so a representative it refuses can arrive after the account has opened. The account then stays attached: the 400 says so, and the merchant lists the processor with representative_prefilled false. Send the same request again with a corrected representative. The open account is reused, so retries never create a second one. The retry reads only the representative: the stored business went with the account when it opened, and a tax_id it did not carry is collected during onboarding.법인의 경우 처리사 쪽에서 계정 개설과 대표자 등록이 두 단계로 이루어지므로, 계정이 열린 뒤에 대표자가 거부될 수 있습니다. 이때 계정은 연결된 상태로 유지됩니다. 400 응답이 이를 알려주며, 가맹점의 processors 항목에 representative_prefilled가 false로 표시됩니다. 수정한 representative와 함께 같은 요청을 다시 보내 주십시오. 열린 계정을 재사용하므로 재시도로 계정이 하나 더 생기지 않습니다. 재시도에서는 representative만 읽습니다. 저장된 business는 계정이 열릴 때 함께 전달되었고, 전달되지 않은 tax_id는 온보딩에서 수집됩니다.
Already attached이미 연결된 경우
A merchant that already has an account for the given processor comes back as a 409, unless that account is still waiting for its representative, which resumes instead. The 409 message says which.해당 결제 처리사의 계정을 이미 보유한 가맹점은 409로 반환됩니다. 다만 그 계정이 아직 대표자를 기다리는 경우에는 409 대신 대표자 등록을 이어서 진행합니다. 어느 쪽인지는 409 메시지가 알려줍니다.
Default rail기본 결제 경로
The first processor a merchant attaches becomes its default_processor, used whenever a charge names none. It does not change on its own when you attach another.가맹점이 처음 연결한 결제 처리사가 default_processor가 되며, 결제 시 처리사를 지정하지 않으면 이 처리사가 사용됩니다. 이후 다른 처리사를 연결해도 자동으로 바뀌지 않습니다.

Conventions규약 Forward-only fields전달 전용 필드·Onboarding is required before charging결제 전 온보딩 필수

Emits이벤트 발행 merchant.updated

Parameters파라미터

Parameter파라미터 In위치 Type타입 Description설명
merchant_id
required 		path string

The merchant id.가맹점 id입니다.

Request body요청 본문

Field필드 Type타입 Description설명
processor
optional 		string

Which processor to attach. Currently only stripe.연결할 결제 처리사입니다. 현재는 stripe만 지원합니다.
tax_id
optional forward-only 		string

Business tax identifier: the EIN for a US business (nine digits, e.g. 12-3456789). Sent to the processor to satisfy its verification.사업자 세금 식별 번호이며, 미국 사업체는 EIN(숫자 9자리, 예: 12-3456789)입니다. 처리사의 검증을 충족하기 위해 전달합니다.
representative
optional forward-only 		object

The person who controls the business. Every field here is forward-only: we pass it to the processor so onboarding stops asking, and keep none of it. Do not send a national ID (SSN). The processor collects that from the merchant directly.사업체를 지배하는 사람입니다. 이곳의 모든 필드는 전달 전용입니다. 온보딩에서 다시 묻지 않도록 처리사에 전달하고 아무것도 보관하지 않습니다. 국가 신분 번호(SSN)는 보내지 마십시오. 처리사가 가맹점에게서 직접 수집합니다.
representative.first_name
optional forward-only 		string
representative.last_name
optional forward-only 		string
representative.email
optional forward-only 		string
representative.phone
optional forward-only 		string

Use E.164: '+', the country code, then the subscriber number, e.g. +12125550123 (US) or +821012345678 (KR). A phone no processor could parse is refused as a 400 invalid_request naming this field.E.164 형식('+', 국가 코드, 가입자 번호 순)을 사용해 주십시오. 예: +12125550123(미국), +821012345678(한국). 어떤 처리사도 해석할 수 없는 전화번호는 이 필드를 지목한 400 invalid_request로 거부됩니다.
representative.date_of_birth
optional forward-only 		string

ISO 8601 date, YYYY-MM-DD, e.g. 1985-04-27. Must be a past date at least 13 years back, the processor's minimum age for a representative.ISO 8601 날짜(YYYY-MM-DD) 형식입니다. 예: 1985-04-27. 최소 13년 전의 과거 날짜여야 하며, 이는 결제 처리사가 요구하는 대표자의 최소 연령입니다.
representative.address
optional forward-only 		object

The representative's home address.대표자의 자택 주소입니다.
representative.address.line1
optional forward-only 		string
representative.address.line2
optional forward-only 		string
representative.address.city
optional forward-only 		string
representative.address.state
optional forward-only 		string

Two-letter state or province code. For a US address, the USPS code. The processor cannot serve US insular areas (GU, VI, AS, MP).두 글자 주/도 코드입니다. 미국 주소는 USPS 코드를 사용하며, 미국 도서 지역(GU, VI, AS, MP)은 결제 처리사가 지원하지 않습니다.
representative.address.postal_code
optional forward-only 		string

Postal code. For a US address, 5 digits or ZIP+4, e.g. 19104 or 19104-2617.우편번호입니다. 미국 주소는 5자리 또는 ZIP+4 형식입니다. 예: 19104, 19104-2617.
representative.address.country
optional forward-only 		string

Two-letter ISO country code, required whenever an address is sent. This is the country of *this address*: a business address must be in the merchant's own country (the top-level country on the merchant), while a representative's home address may be anywhere.두 글자 ISO 국가 코드로, 주소를 보내실 때는 필수입니다. 이는 *이 주소*의 국가입니다. 사업장 주소는 가맹점 자신의 국가(가맹점의 최상위 country)에 있어야 하며, 대표자의 자택 주소는 어느 국가든 가능합니다.

Example request요청 예시

<?php
$ch = curl_init("https://api.outlinepay.com/v1/merchants/mrc_9f2c8bAaZ1kQ/processors");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer olp_sk_test_YOUR_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "tax_id"         => "00-0000000",
        "representative" => [
            "first_name"    => "Dana",
            "last_name"     => "Whitfield",
            "email"         => "[email protected]",
            "phone"         => "+12125550188",
            "date_of_birth" => "1985-04-27",
            "address"       => [
                "line1"       => "220 Spruce St",
                "city"        => "Philadelphia",
                "state"       => "PA",
                "postal_code" => "19106",
                "country"     => "US",
            ],
        ],
    ]),
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Response응답

Returns a Merchant.Merchant 객체를 반환합니다.

Response응답 · 200 
{
  "id": "mrc_9f2c8bAaZ1kQ",
  "object": "merchant",
  "name": "Acme Trading Co.",
  "email": "[email protected]",
  "status": "created",
  "mode": "test",
  "entity_type": "company",
  "business": {
    "legal_name": "Acme Trading Co. LLC",
    "structure": "llc",
    "phone": "+12125550123",
    "url": "https://acme.example",
    "product_description": "Imported kitchenware and small appliances.",
    "industry_code": "5722",
    "statement_descriptor": "ACME TRADING",
    "address": {
      "line1": "1600 Market St",
      "city": "Philadelphia",
      "state": "PA",
      "postal_code": "19103",
      "country": "US"
    }
  },
  "metadata": {
    "shop_id": "shop-4821"
  },
  "processors": [
    {
      "processor": "stripe",
      "account_id": "acct_1AbCdEfGhIjKlMnO",
      "onboarding_completed": false,
      "verified": false,
      "representative_prefilled": true
    }
  ],
  "created_at": "2026-07-21T12:00:00Z"
}

POST /v1/merchants/{id}/account_session

Create an account session계정 세션 생성

Returns a short-lived client_secret your page hands to the processor's embedded components, plus the publishable key and the merchant's locale. Your server is the authorization gate. It decides which logged-in merchant a session is for. See components below for the full set.귀사의 페이지가 결제 처리사의 임베드 컴포넌트에 전달할 단기 client_secret과 공개 키, 그리고 가맹점의 locale을 반환합니다. 어느 로그인 가맹점을 위한 세션인지 판단하는 인가 주체는 귀사의 서버입니다. 전체 목록은 아래 components를 참고해 주십시오.

This is the step that makes an attached merchant chargeable: the onboarding component is the only place a merchant completes its verification, so nothing can be charged until it has been rendered and finished. See the Quickstart for a worked example of both halves.연결된 가맹점이 실제로 결제를 받을 수 있게 되는 단계가 바로 이 단계입니다. 가맹점의 검증은 오직 온보딩 컴포넌트 안에서만 완료되므로, 이 컴포넌트를 렌더링해 완료하기 전까지는 어떤 결제도 받을 수 없습니다. 양쪽 구현 예시는 시작하기 가이드를 참고해 주십시오.

Attach a processor first결제 처리사를 먼저 연결하십시오
A session is scoped to the merchant's connected account, so it needs one to exist. Without it this returns 400 invalid_request, "This merchant has no processor yet. Attach one first."세션은 가맹점의 연결 계정을 대상으로 하므로, 해당 계정이 먼저 존재해야 합니다. 연결되어 있지 않으면 400 invalid_request와 함께 "This merchant has no processor yet. Attach one first."를 반환합니다.
What to do with the client_secretclient_secret 사용 방법
Hand it back to your own page and give it to the processor's SDK, then create the onboarding component. Your server makes this call so your secret key never reaches the browser, and your page asks an endpoint of yours for the secret.반환된 값을 귀사의 페이지로 전달하고, 이를 결제 처리사의 SDK에 넘긴 뒤 온보딩 컴포넌트를 생성하십시오. 이 호출은 귀사의 서버가 수행하므로 시크릿 키가 브라우저에 노출되지 않으며, 페이지는 귀사의 엔드포인트에 secret을 요청합니다.
Mint a fresh one every time매번 새로 발급하십시오
The session is short-lived and the SDK asks for a new secret by itself when it lapses mid-form, which is why it takes a function rather than a string. Point that function at an endpoint that calls this one afresh. Handing back a cached secret strands the merchant partway through onboarding.세션은 유효 기간이 짧고, 양식 작성 중 만료되면 SDK가 스스로 새 secret을 요청합니다. 문자열이 아니라 함수를 받는 이유가 바로 이것입니다. 해당 함수는 이 엔드포인트를 매번 새로 호출하는 귀사의 엔드포인트를 가리키게 해 주십시오. 캐시된 secret을 반환하면 가맹점이 온보딩 도중에 멈추게 됩니다.
Do not send an Idempotency-KeyIdempotency-Key를 보내지 마십시오
Idempotency keys are ignored here: a replayed response would carry an expired client_secret, and creating a second session is harmless.이 엔드포인트에서 Idempotency-Key는 무시됩니다. 저장된 응답을 재생하면 이미 만료된 client_secret이 전달되고, 세션이 두 번 생성되어도 아무런 문제가 없기 때문입니다.
How you know onboarding finished온보딩 완료 확인 방법
processors[].onboarding_completed turns true when the merchant submits, and processors[].verified turns true when the processor accepts. The merchant's status turns active at that moment and we emit merchant.updated. The component's own callbacks mean the form closed, not that the merchant was accepted, so read the merchant.가맹점이 제출하면 processors[].onboarding_completed가 true가 되고, 결제 처리사가 승인하면 processors[].verified가 true가 됩니다. 이 시점에 가맹점의 status가 active로 바뀌고 merchant.updated 이벤트를 발송합니다. 컴포넌트 자체의 콜백은 양식이 닫혔다는 뜻일 뿐 승인되었다는 뜻이 아니므로, 가맹점 객체를 확인해 주십시오.
Not gated on onboarding온보딩 여부로 제한하지 않습니다
This endpoint is not refused for a merchant that has not onboarded, since it is the way out of a 409 merchant_not_onboarded.이 엔드포인트는 온보딩하지 않은 가맹점도 거부하지 않습니다. 409 merchant_not_onboarded를 해결하는 경로가 바로 이 엔드포인트이기 때문입니다.
The onboarding component shows our merchant terms first온보딩 컴포넌트는 당사의 가맹점 약관을 먼저 표시합니다
When the response's terms.required is true, outlinepay.js frames terms.url ahead of the processor's form and the merchant accepts the OutlinePay merchant terms there, once, for every processor. The merchant object's terms_acceptance and a merchant.updated event record it. If your Content-Security-Policy sets frame-src, allow the origin of terms.url.응답의 terms.required가 true이면 outlinepay.js가 결제 처리사의 양식에 앞서 terms.url을 프레임으로 표시하고, 가맹점은 그곳에서 OutlinePay 가맹점 약관에 한 번 동의하며 이는 모든 결제 처리사에 적용됩니다. 가맹점 객체의 terms_acceptance와 merchant.updated 이벤트가 이를 기록합니다. Content-Security-Policy에 frame-src를 설정하셨다면 terms.url의 오리진을 허용해 주십시오.

Conventions규약 Onboarding is required before charging결제 전 온보딩 필수·Processor-agnostic values프로세서 독립 값

Parameters파라미터

Parameter파라미터 In위치 Type타입 Description설명
id
required 		path string

The merchant id.가맹점 id입니다.

Request body요청 본문

Field필드 Type타입 Description설명
components
required 		array<string>

Which components to scope the session to, in OutlinePay's processor-agnostic vocabulary. Required: a session grants exactly what you name here, so name only what the page mounts. Note: your browser still mounts each one with the processor's own SDK (for Stripe, Connect.js), which uses its own component ids.세션의 범위를 지정할 컴포넌트이며, OutlinePay의 처리사 독립 용어입니다. 필수 항목입니다. 세션은 여기에 지정하신 컴포넌트만 정확히 허용하므로, 페이지가 마운트하는 것만 지정해 주십시오. 참고로 브라우저에서는 여전히 처리사 자신의 SDK(Stripe는 Connect.js)로 각 컴포넌트를 마운트하며, SDK는 자체 컴포넌트 id를 사용합니다.

Example request요청 예시

<?php
$ch = curl_init("https://api.outlinepay.com/v1/merchants/mrc_9f2c8bAaZ1kQ/account_session");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer olp_sk_test_YOUR_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "components" => [
            "onboarding",
        ],
    ]),
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Response응답

Field필드 Type타입 Description설명
object string

The literal string account_session.고정 문자열 account_session입니다.
processor string

The processor these credentials belong to, e.g. stripe.이 자격 증명이 속한 결제 처리사입니다. 예: stripe.
client_secret string
publishable_key string
components array<string>
locale string

The merchant's language, spelled the way this processor's SDK wants it. Pass it straight through when you initialise the components. It is not the tag you sent us on the merchant: Stripe's embedded components accept only regional codes, so a merchant stored as ko comes back here as ko-KR, and a language the SDK cannot render falls back to en-US rather than failing. Setting the merchant's locale alone does not translate the form. The SDK has to be told.가맹점의 언어를 이 처리사의 SDK가 원하는 표기로 반환합니다. 컴포넌트를 초기화하실 때 그대로 전달해 주십시오. 가맹점에 보내신 태그와는 다릅니다. Stripe의 임베드 컴포넌트는 지역 코드만 허용하므로 ko로 저장된 가맹점은 여기서 ko-KR로 반환되고, SDK가 렌더링할 수 없는 언어는 실패하는 대신 en-US로 대체됩니다. 가맹점의 locale 설정만으로는 양식이 번역되지 않습니다. SDK에 알려 주어야 합니다.
terms object

Whether this merchant still has to accept the OutlinePay merchant terms, and where they are shown. outlinepay.js reads this on its own: when required is true, mounting the onboarding component shows the terms screen at url first, and the processor's form after the merchant agrees. Keep forwarding this response body verbatim. url is short-lived and scoped to this one merchant, minted fresh with every session. If your Content-Security-Policy sets frame-src, allow the origin of url.이 가맹점이 아직 OutlinePay 가맹점 약관에 동의해야 하는지, 그리고 약관이 어디에 표시되는지를 담습니다. outlinepay.js가 스스로 읽는 값으로, required가 true이면 온보딩 컴포넌트를 마운트할 때 url의 약관 화면이 먼저 표시되고 가맹점이 동의한 뒤 결제 처리사의 양식이 나타납니다. 이 응답 본문을 지금처럼 그대로 전달해 주십시오. url은 수명이 짧고 이 가맹점 하나에만 유효하며 세션을 발급할 때마다 새로 생성됩니다. Content-Security-Policy에 frame-src를 설정하셨다면 url의 오리진을 허용해 주십시오.
terms.required boolean

True until the merchant has accepted the current terms version.가맹점이 현재 약관 버전에 동의하기 전까지 true입니다.
terms.url string

The terms screen to frame, or null when required is false.프레임으로 표시할 약관 화면이며, required가 false이면 null입니다. nullable
Response응답 · 200 
{
  "object": "account_session",
  "processor": "stripe",
  "client_secret": "accs_secret_9f2c8b...",
  "publishable_key": "pk_test_51...",
  "components": [
    "onboarding"
  ],
  "locale": "ko-KR",
  "terms": {
    "required": true,
    "url": "https://outlinepay.com/embedded/merchant-terms?token=eyJfcmFpbHMi..."
  }
}

Object객체

The Payment objectPayment 객체

A single charge. Creation returns a hosted checkout_url. The outcome arrives by webhook.한 건의 결제입니다. 생성 시 호스팅 checkout_url이 반환되며, 결과는 웹훅으로 전달됩니다.

Lifecycle · card, wallet, bnpl상태 흐름 · card, wallet, bnpl

Instant methods즉시 확정 수단
awaiting_payment ---------------------> succeeded
       |
       '--------------------> expired

Instant methods settle at checkout, so there are only two ways out: the customer completes the payment (succeeded), or the checkout lapses at expires_at (expired). A declined card does not fail the payment. The customer just retries on the checkout page, so the payment stays awaiting_payment until one of the two.즉시 확정 수단은 체크아웃 시점에 결제가 확정되므로 결과는 두 가지뿐입니다. 고객이 결제를 완료하면 succeeded, 체크아웃이 expires_at에 만료되면 expired입니다. 카드 승인 거절은 결제를 실패시키지 않습니다. 고객이 체크아웃 페이지에서 다시 시도할 뿐이므로, 둘 중 하나가 되기 전까지 결제는 awaiting_payment로 유지됩니다.

Lifecycle · bank_debit, bank_transfer상태 흐름 · bank_debit, bank_transfer

Delayed methods지연 정산 수단
awaiting_payment ----> processing ----> succeeded
       |                   |
       '--> expired        '--------> failed

Bank rails settle after the customer finishes, so a third state sits in the middle: processing means paid but not settled, and it can last days (an ACH debit takes up to four business days, longer on microdeposit verification). Do not fulfill on processing. failed is genuinely reachable here, after the customer has done everything right. failure_reason says why and what to do next.은행 결제는 고객이 결제를 마친 뒤에 정산되므로 중간에 상태가 하나 더 있습니다. processing은 결제는 되었지만 아직 정산되지 않았다는 뜻이며, 며칠간 지속될 수 있습니다(ACH 출금은 영업일 기준 최대 4일, 소액 입금 검증 시 더 길어집니다). processing 상태에서 상품을 발송하지 마십시오. 이 흐름에서는 고객이 모든 절차를 마친 뒤에도 failed가 실제로 발생할 수 있으며, 원인과 다음 조치는 failure_reason에 담깁니다.

Field필드 Type타입 Description설명
id string
object string

The literal string payment, naming this resource's type. Every resource carries one, and it is the discriminator for an event's data.고정 문자열 payment로, 이 리소스의 타입을 나타냅니다. 모든 리소스가 이 필드를 가지며, 이벤트 data의 판별자이기도 합니다.
status enum

Where the payment is. Both lifecycles are drawn under The Payment object.결제가 어느 단계에 있는지입니다. 두 상태 흐름 모두 The Payment object 아래에 그림으로 정리되어 있습니다.

awaiting_payment: the customer has not finished. A declined card does not end this state. The customer retries on the checkout page.awaiting_payment: 고객이 아직 결제를 마치지 않았습니다. 카드 승인 거절은 이 상태를 끝내지 않습니다. 고객이 체크아웃 페이지에서 다시 시도합니다.

processing: the customer has paid but the money is still moving. Only delayed methods (bank_debit, bank_transfer) reach it, it can last days, and nothing is decided yet, so do not fulfill on it.processing: 고객은 결제했지만 자금이 아직 이동 중입니다. 지연 정산 수단(bank_debit, bank_transfer)만 이 상태에 도달하며, 며칠간 지속될 수 있고 아직 아무것도 확정되지 않았으므로 이 상태에서 상품을 발송하지 마십시오.

failed: reachable only from processing, so only on delayed methods. failure_reason says why.failed: processing에서만 도달하므로 지연 정산 수단에서만 발생합니다. 원인은 failure_reason에 담깁니다.

One of다음 중 하나
mode enum

The world this object lives in, test (sandbox) or live. Matches your API key's prefix (olp_sk_test_ / olp_sk_live_).이 객체가 속한 환경으로, test(샌드박스) 또는 live입니다. API 키의 접두사(olp_sk_test_ / olp_sk_live_)와 일치합니다.

One of다음 중 하나
merchant_id string
amount integer

Minor units of currency (for usd, cents).currency의 최소 단위 정수입니다(usd는 센트).
currency enum

What the customer was charged in, unless localized_pricing was on and they took the converted price, in which case presentment says what they paid. usd is the only currency we support today.고객에게 청구된 통화입니다. 다만 localized_pricing이 켜져 있고 고객이 환산된 금액을 선택한 경우에는 presentment에 실제 결제 금액이 담깁니다. 현재 지원 통화는 usd뿐입니다.

One of다음 중 하나
description string nullable
customer object

The customer details you sent at creation, echoed in the same shape. Null when you sent none.생성 시 보내신 고객 정보를 같은 형태로 반환합니다. 보내지 않으셨다면 null입니다. nullable
customer.email string
fees object

Fees charged on the gross amount, in minor units. Refunds do not return fees.총액 기준으로 부과된 수수료이며 최소 단위입니다. 환불 시에도 수수료는 반환되지 않습니다.

outline and partner are frozen as soon as they are knowable, which for almost every payment is creation time. A later rate change does not touch them.outline과 partner는 확정 가능해지는 즉시 고정되며, 대부분의 결제에서는 생성 시점입니다. 이후의 요율 변경은 영향을 주지 않습니다.

The exception is a checkout whose fee depends on which method the customer picks (a capped bank rail offered beside an uncapped one). There, outline and partner stay null until the customer answers on the hosted checkout page, and selected_payment_method says whether they have. A payment that expires unanswered keeps null.예외는 고객이 선택하는 수단에 따라 수수료가 달라지는 체크아웃입니다(상한이 있는 은행 수단을 상한 없는 수단과 함께 제공하는 경우). 이때 outline과 partner는 고객이 호스팅 체크아웃 페이지에서 답할 때까지 null로 유지되며, 답했는지는 selected_payment_method로 알 수 있습니다. 답 없이 만료된 결제는 계속 null입니다.
fees.processor integer

The processor's own cut, read from the charge's balance transactions (see the top-level processor field for which processor).결제 처리사 자신의 몫으로, 결제 건의 잔액 거래에서 읽어 옵니다(어느 처리사인지는 최상위 processor 필드 참고).

Null until captured, a moment after the outcome. That means it is still null on the payment.succeeded or payment.failed event; the payment.updated event that follows carries it.확정 전까지 null이며, 결과 직후에 확정됩니다. 따라서 payment.succeeded나 payment.failed 이벤트 시점에는 아직 null이고, 뒤따르는 payment.updated 이벤트에 담겨 옵니다.

Set on failed payments too. There it is the processor's flat charge for a returned bank debit, and the only fee borne: a failed payment collects nothing for OutlinePay or for you.실패한 결제에도 설정됩니다. 이때는 반환된 은행 출금에 대한 처리사의 정액 수수료이며, 유일하게 부과되는 수수료입니다. 실패한 결제에서는 OutlinePay도 귀사도 아무것도 수취하지 않습니다. nullable
fees.outline integer

OutlinePay's fee, from the rate card. Same in test and live.OutlinePay의 수수료로, 요율표 기준입니다. 테스트와 라이브가 동일합니다.

Null while a method choice is still outstanding. 0 on a payment that failed or expired, because the processor returns this fee when a debit is returned.수단 선택이 남아 있는 동안은 null입니다. 실패하거나 만료된 결제에서는 0입니다. 출금이 반환되면 처리사가 이 수수료를 돌려주기 때문입니다. nullable
fees.partner integer

Your fee, at your configured rate.귀사의 수수료로, 설정하신 요율이 적용됩니다.

Null while a method choice is still outstanding. 0 on a payment that failed or expired, since nothing was collected.수단 선택이 남아 있는 동안은 null입니다. 실패하거나 만료된 결제에서는 수취된 금액이 없으므로 0입니다. nullable
fees.dispute integer

What the disputes on this payment cost, summed: the same money that is itemised per-dispute on disputes[].fee. 0 when there are none.이 결제의 분쟁에 든 비용의 합계로, disputes[].fee에 건별로 표시되는 것과 같은 금액입니다. 분쟁이 없으면 0입니다.
fees.invoice integer

What the payment processor charged the merchant for issuing the invoice, before tax, on a payment created with invoice.enabled. fees.tax.invoice carries the tax, and the two add up to what the merchant paid. Null on every payment that did not ask for one.invoice.enabled로 생성된 결제에서, 결제 처리사가 인보이스 발행 대가로 가맹점에 부과한 금액이며 세금은 제외된 금액입니다. 세금은 fees.tax.invoice에 담기며, 두 값을 더하면 가맹점이 실제로 부담한 금액이 됩니다. 인보이스를 요청하지 않은 결제에서는 항상 null입니다.

Live mode only, and slow. The processor itemises this fee only in a report that lands about five days after the payment, so the figure arrives then, on its own payment.updated event. Null until it does, and always null in test mode.라이브 모드에서만 제공되며 늦게 도착합니다. 처리사는 이 수수료의 결제별 내역을 결제 시점보다 약 5일 뒤에 나오는 리포트로만 제공하므로, 금액은 그때 별도의 payment.updated 이벤트로 도착합니다. 그전까지는 null이며, 테스트 모드에서는 항상 null입니다. nullable
fees.fraud_screening integer

What the payment processor charged the merchant for screening this payment for fraud, before tax. fees.tax.fraud_screening carries the tax. Like fees.invoice it is reported late: the figure arrives about five days after the payment, on its own payment.updated event.결제 처리사가 이 결제의 사기 심사(fraud screening) 대가로 가맹점에 부과한 금액이며 세금은 제외된 금액입니다. 세금은 fees.tax.fraud_screening에 담깁니다. fees.invoice와 마찬가지로 늦게 보고됩니다. 금액은 결제 시점보다 약 5일 뒤에 별도의 payment.updated 이벤트로 도착합니다.

Null until it does, always null in test mode, and null for good on a merchant the processor does not bill for screening, which some are not. pending is what tells those apart. While fraud_screening is listed there a figure is still coming, and once it is not, null means no charge.도착 전까지는 null이고, 테스트 모드에서는 항상 null이며, 결제 처리사가 사기 심사 요금을 부과하지 않는 가맹점에서는 계속 null로 남습니다. 그런 가맹점도 있습니다. 두 경우를 구분하는 값이 pending입니다. fraud_screening이 pending에 있는 동안에는 금액이 아직 오는 중이며, 목록에서 빠진 뒤의 null은 부과된 금액이 없다는 뜻입니다. nullable
fees.tax object

Tax the payment processor charged on its own fees, one entry per fee that can carry it. The rate follows the merchant's business address, so it differs by merchant. 0 has two causes: the fee is not taxed where the merchant is, or this payment's share of the tax came to under half a cent.결제 처리사가 자사 수수료에 부과한 세금이며, 세금이 붙을 수 있는 수수료마다 하나씩 항목이 있습니다. 세율은 가맹점의 사업장 주소를 따르므로 가맹점마다 다릅니다. 0은 두 가지를 뜻합니다. 가맹점 소재지에서 그 수수료에 세금이 붙지 않거나, 이 결제 한 건에 해당하는 세액이 0.5센트 미만인 경우입니다.

Each entry is null exactly while the fee it belongs to is null, since both are read from one line of the same report. Add an entry to its fee for what the merchant actually paid.각 항목은 해당 수수료가 null인 동안에만 null입니다. 두 값이 같은 리포트의 한 줄에서 함께 읽히기 때문입니다. 가맹점이 실제로 부담한 금액은 항목과 해당 수수료를 더하시면 됩니다.

Only the processor's product fees are taxed. Payment processing is not, so there is no entry for processor, and OutlinePay adds no tax to its own fee or to yours.세금이 붙는 것은 처리사의 부가 상품 수수료뿐입니다. 결제 처리 수수료에는 붙지 않으므로 processor에 대응하는 항목은 없으며, OutlinePay는 자사 수수료와 파트너 수수료에 세금을 더하지 않습니다.
fees.tax.invoice integer

Tax on fees.invoice.fees.invoice에 부과된 세금입니다. nullable
fees.tax.fraud_screening integer

Tax on fees.fraud_screening.fees.fraud_screening에 부과된 세금입니다. nullable
fees.total integer

Every fee borne on this payment: the sum of the fields above it, tax included (processor + outline + partner + dispute + invoice + fraud_screening + tax.invoice + tax.fraud_screening).이 결제에 부과된 모든 수수료로, 바로 위 필드들의 합이며 세금이 포함되어 있습니다(processor + outline + partner + dispute + invoice + fraud_screening + tax.invoice + tax.fraud_screening).

Counts an uncaptured processor fee as 0. Null while a method choice is outstanding.아직 확정되지 않은 처리사 수수료는 0으로 계산합니다. 수단 선택이 남아 있는 동안은 null입니다. nullable
fees.pending array<string>

The fee lines above that have not arrived yet and are still expected, so the figures beside them will still change. Empty once nothing is outstanding, which is the usual answer. Read this to tell a settled figure from an unsettled one: a null fee that is not listed here is not coming.위 수수료 항목 중 아직 도착하지 않았고 앞으로 도착할 예정인 항목들입니다. 해당 항목의 금액은 앞으로 변경됩니다. 남은 항목이 없으면 빈 배열이며, 대부분의 결제에서는 빈 배열입니다. 금액이 확정되었는지는 이 값으로 판단해 주십시오. 이 목록에 없는 null 값은 앞으로도 도착하지 않습니다.

A pending line counts as 0 until it lands, so total reads low and merchant_net reads high while anything is listed here. Wait for the payment.updated event that empties this before you record either figure.도착하지 않은 항목은 도착 전까지 0으로 계산하므로, 이 목록에 항목이 남아 있는 동안에는 total이 실제보다 낮게, merchant_net이 실제보다 높게 표시됩니다. 두 값을 기록하실 때는 이 목록이 비워지는 payment.updated 이벤트를 기다려 주십시오.

A line leaves the list when its figure arrives, or when we stop expecting it, which is 14 days after the payment for invoice and fraud_screening. Neither is ever listed in test mode, where they never arrive at all. Disputes are never listed: one can open months later and add a fee to a payment that had none.항목은 금액이 도착하거나 당사가 더 이상 기다리지 않게 되면 목록에서 빠집니다. invoice와 fraud_screening의 대기 기간은 결제 시점부터 14일입니다. 두 항목은 테스트 모드에서는 표시되지 않습니다. 테스트 모드에서는 아예 도착하지 않기 때문입니다. 분쟁 수수료는 목록에 포함되지 않습니다. 분쟁은 수개월 뒤에도 제기되어 수수료가 없던 결제에 수수료를 더할 수 있기 때문입니다.
merchant_net integer

What the merchant ends up with: amount − amount_refunded − amount_disputed − fees.total.가맹점에 최종적으로 남는 금액입니다. amount − amount_refunded − amount_disputed − fees.total.

Reads high until the processor's fee lands, a moment after the outcome, including on the payment.succeeded event itself. Record net from the payment.updated event that follows.처리사 수수료가 확정되기 전까지는 실제보다 높게 읽히며, payment.succeeded 이벤트 시점도 마찬가지입니다. 순수령액은 뒤따르는 payment.updated 이벤트 기준으로 기록해 주십시오.

Null while a method choice is outstanding, alongside fees.total.수단 선택이 남아 있는 동안은 fees.total과 함께 null입니다.

Can go negative. A refund returns the principal and keeps every fee, so a fully refunded payment nets the negative of its fees. On a payment that failed or expired there is no principal at all, so this is the negative of the processor's charge for the failure (its flat fee for a returned bank debit), and 0 until that charge has been read.음수가 될 수 있습니다. 환불은 원금만 돌려주고 수수료는 모두 유지되므로, 전액 환불된 결제의 순수령액은 수수료의 음수가 됩니다. 실패하거나 만료된 결제에는 원금 자체가 없으므로, 실패에 대해 처리사가 부과한 금액(반환된 은행 출금에 대한 정액 수수료)의 음수가 되며, 그 금액을 읽어 오기 전까지는 0입니다. nullable
amount_refunded integer

Sum of non-failed refunds, in minor units.실패하지 않은 환불의 합계이며 최소 단위입니다.
amount_disputed integer

Sum of disputes[].amount_withheld: what the processor is holding back over open or lost disputes, in minor units. Returns to 0 when a dispute is won.disputes[].amount_withheld의 합계입니다. 진행 중이거나 패소한 분쟁에 대해 결제 처리사가 보류하고 있는 금액이며 최소 단위입니다. 승소하면 0으로 돌아갑니다.
amount_refundable integer

amount − amount_refunded: headroom for a further refund. Reaches 0 at a full refund, and is 0 on any payment that did not settle, since only a succeeded payment can be refunded. Also 0 while a dispute is holding the money (disputes[].amount_withheld above zero), which the processor refuses to refund whether the dispute is open or already lost. It becomes refundable again if the dispute is won.amount − amount_refunded: 추가로 환불할 수 있는 여유분입니다. 전액 환불 시 0이 되고, 정산되지 않은 결제에서도 0입니다. succeeded인 결제만 환불할 수 있기 때문입니다. 분쟁이 자금을 보류 중인 동안(disputes[].amount_withheld가 0 초과)에도 0입니다. 분쟁이 진행 중이든 이미 패소했든 처리사가 환불을 거부하며, 승소하면 다시 환불 가능해집니다.
refunds array<object>

Refunds against this payment, oldest first.이 결제에 대한 환불 목록이며 오래된 순입니다.
refunds[].id string
refunds[].status enum

failed also covers a refund the processor withdrew rather than refused, so the two are told apart by failure_reason, not by the status.failed에는 처리사가 거절한 환불뿐 아니라 철회한 환불도 포함됩니다. 둘은 상태가 아니라 failure_reason으로 구분하십시오.

One of다음 중 하나
refunds[].amount integer

Minor units.최소 단위입니다.
refunds[].failure_reason enum

Why a refund did not reach the customer, in OutlinePay's vocabulary, translated from the processor's own failure code at the boundary. Null unless the refund failed.환불이 고객에게 도달하지 못한 이유로, 처리사의 실패 코드를 경계에서 OutlinePay의 용어로 변환한 값입니다. 환불이 실패하지 않았다면 null입니다.

card_unusable: the card can't be refunded to. It was reported lost or stolen, or it's expired or canceled. Refund the customer another way, retrying will fail again.card_unusable: 해당 카드로는 환불할 수 없습니다. 분실이나 도난으로 신고되었거나, 만료 또는 해지된 카드입니다. 다시 시도해도 실패하므로 다른 방법으로 환불하십시오.

insufficient_funds: the merchant's balance didn't have enough to cover the refund. Retry after it funds.insufficient_funds: 가맹점 잔액이 환불액에 미치지 못했습니다. 잔액이 채워진 뒤 다시 시도하십시오.

declined: the card issuer declined the refund. Retry once, then refund another way if it declines again.declined: 카드 발급사가 환불을 거절했습니다. 한 번 다시 시도하고, 또 거절되면 다른 방법으로 환불하십시오.

disputed: the charge is under dispute. Do not retry, the dispute governs this refund now.disputed: 해당 결제가 분쟁 중입니다. 이제 이 환불은 분쟁 절차를 따르므로 다시 시도하지 마십시오.

canceled: the refund was withdrawn, not refused. Nothing to retry, create a new refund if one is still owed.canceled: 환불이 거절된 것이 아니라 철회되었습니다. 다시 시도할 것은 없으며, 환불이 여전히 필요하다면 새 환불을 생성하십시오.

other: the processor gave a reason we don't have a word for, or gave none. Treat it as a failure with no further guidance.other: 처리사가 대응하는 단어가 없는 이유를 제시했거나 이유를 제시하지 않았습니다. 추가 안내가 없는 실패로 처리하십시오. nullable

One of다음 중 하나
refunds[].metadata object

Your own key/value pairs, for correlating this object back to your records. We never interpret the contents: they are stored, returned on every read, and carried on every event this object emits. A payment's, refund's or payment link's is also forwarded to the processor. A merchant's is not. At most 50 pairs, keys up to 40 characters, values up to 500. Values are stored as strings. Keys beginning outlinepay_, plus outline_fee and partner_fee, are reserved by OutlinePay and rejected. Never put secrets here.이 객체를 귀사의 기록과 연결하기 위한 자체 키/값 쌍입니다. OutlinePay는 내용을 해석하지 않습니다. 저장되고, 모든 조회에 반환되며, 이 객체가 발행하는 모든 이벤트에 실립니다. 결제, 환불, 결제 링크의 메타데이터는 결제 처리사에도 전달되며, 가맹점의 메타데이터는 전달되지 않습니다. 최대 50쌍, 키는 40자, 값은 500자까지이며 문자열로 저장됩니다. outlinepay_로 시작하는 키와 outline_fee, partner_fee는 OutlinePay가 예약하고 있어 거부됩니다. 비밀 정보는 절대 넣지 마십시오.
refunds[].created_at string

ISO 8601 UTC.ISO 8601 UTC 형식입니다.
disputes array<object>

Chargebacks against this payment, oldest first. Usually empty.이 결제에 대한 지불 거절 목록이며 오래된 순입니다. 보통은 비어 있습니다.
disputes[].id string
disputes[].status enum

The chargeback's state, in OutlinePay's vocabulary and translated from whichever processor reported it. The inquiry_* set is the card networks' early retrieval request, raised before a formal chargeback. The rest is the real lifecycle, terminating in won/lost, or refunded when the merchant refunds instead of contesting.지불 거절의 상태로, OutlinePay의 용어이며 어느 처리사가 보고했든 변환되어 있습니다. inquiry_* 계열은 정식 지불 거절 전에 제기되는 카드 네트워크의 사전 조회 요청이고, 나머지가 실제 라이프사이클입니다. won/lost로 끝나거나, 가맹점이 다투는 대신 환불하면 refunded가 됩니다.

One of다음 중 하나
disputes[].reason enum

Why the cardholder disputed, in OutlinePay's vocabulary, translated from the processor's own reason codes. bank_error covers the several ways a bank can decline to move the money, and anything we cannot place maps to other.카드 소지자가 지불 거절을 제기한 사유로, 처리사의 사유 코드를 OutlinePay의 용어로 변환한 값입니다. bank_error는 은행이 자금 이동을 거절하는 여러 경우를 묶은 값이고, 분류할 수 없는 값은 other로 대응됩니다. nullable

Accepted values (10)허용 값 (10개)
disputes[].amount integer

Minor units.최소 단위입니다.
disputes[].fee integer

What the processor charged the merchant to handle this dispute, in minor units (Stripe bills a flat 15.00 USD). Charged whether the dispute is won or lost. The payment's fees.total and merchant_net account for it.이 분쟁의 처리 대가로 처리사가 가맹점에 청구한 금액이며 최소 단위입니다(Stripe는 정액 15.00 USD). 승패와 무관하게 청구됩니다. 결제의 fees.total과 merchant_net에 반영됩니다. nullable
disputes[].amount_withheld integer

How much of the payment the processor is currently holding back over this dispute, in minor units. Equal to amount from the moment a dispute opens, and 0 once the merchant wins. While it is above zero the payment cannot be refunded and amount_refundable reads 0.이 분쟁으로 처리사가 현재 보류 중인 결제 금액이며 최소 단위입니다. 분쟁이 열리는 순간부터 amount와 같고, 가맹점이 승소하면 0이 됩니다. 0보다 큰 동안에는 결제를 환불할 수 없으며 amount_refundable이 0으로 표시됩니다. nullable
disputes[].evidence_due_at string

Deadline to submit evidence, ISO 8601 UTC.증빙 제출 기한이며 ISO 8601 UTC 형식입니다. nullable
disputes[].created_at string

ISO 8601 UTC.ISO 8601 UTC 형식입니다.
processor string

The underlying processor, e.g. stripe.기반 결제 처리사입니다. 예: stripe.
processor_payment_method string

What actually settled, in the processor's own vocabulary (for example card or us_bank_account). Like every processor_ field it is outside our portability contract: read it for display or for reconciling against your processor, not for product logic.실제로 정산된 수단으로, 처리사 자신의 용어입니다(예: card, us_bank_account). 다른 processor_ 필드와 마찬가지로 이식성 계약 밖에 있습니다. 표시 용도나 처리사와의 대사에는 사용하시되 제품 로직에는 사용하지 마십시오.

Null until the charge exists, which for a delayed method such as ACH is days after the payment was created. It is read off the charge at the same moment as fees.processor and arrives on the same payment.updated event.결제 건이 생기기 전까지 null이며, ACH 같은 지연 수단에서는 결제 생성 후 며칠 뒤입니다. fees.processor와 같은 순간에 읽혀 같은 payment.updated 이벤트로 도착합니다.

link covers anything paid through the processor's wallet, including a bank account paid through it, so it does not say whether a card was involved.link는 처리사의 지갑을 통해 결제된 모든 경우를 포괄하며 지갑을 통한 은행 계좌 결제도 포함하므로, 카드 사용 여부를 알려 주지 않습니다. nullable
processor_reference string

The processor's own identifier for this transaction, to quote back when reconciling against it. It is the reference on the receipt and the invoice the processor issues the merchant, and on the processor's billing for the fees it charges the merchant directly, none of which carry an OutlinePay id. The processor_ prefix carries the same warning as the field above, and its shape differs by processor.이 거래에 대한 처리사 자신의 식별자로, 처리사와 대사하실 때 제시하는 값입니다. 처리사가 가맹점에 발행하는 영수증과 인보이스, 그리고 처리사가 가맹점에 직접 청구하는 수수료 내역에 적히는 참조 번호이며, 이들 중 어디에도 OutlinePay의 id는 없습니다. processor_ 접두사가 뜻하는 바는 바로 위 필드와 같으며, 값의 형식은 처리사마다 다릅니다.

Null until a charge exists, arriving on the same payment.updated that fills fees.processor and processor_payment_method. A failed payment can carry one, because a decline and a returned bank debit both produced a charge, so a value here is not proof that money moved. The reference has been recorded since 2026-09-03, so a payment charged before that date reads null.결제 건이 생기기 전까지 null이며, fees.processor와 processor_payment_method를 채우는 같은 payment.updated 이벤트로 도착합니다. 실패한 결제에도 값이 있을 수 있습니다. 카드 거절과 반환된 은행 출금 모두 결제 건을 만들기 때문이며, 따라서 값이 있다는 것이 돈이 움직였다는 뜻은 아닙니다. 이 참조 번호는 2026년 9월 3일부터 기록되었으므로, 그 이전에 결제 건이 생성된 결제는 null로 표시됩니다. nullable
selected_payment_method enum

A payment-method category a partner may offer, in OutlinePay's vocabulary, translated to the processor's own methods at the boundary.파트너가 제공할 수 있는 결제 수단 분류로, OutlinePay의 용어이며 경계에서 처리사의 수단으로 변환됩니다.

card is debit and credit cards. The card-based wallets (Apple Pay, Google Pay, Link) ride along automatically and cannot be offered without cards. wallet is the standalone wallets (Cash App, Amazon Pay). bnpl is buy-now-pay-later (Klarna, Affirm, Afterpay). bank_debit is ACH Direct Debit, paid from a US bank account. bank_transfer is a push transfer: the customer is shown a virtual account number and sends the funds from their own bank.card는 체크카드와 신용카드입니다. 카드 기반 간편결제(Apple Pay, Google Pay, Link)는 자동으로 함께 제공되며 카드 없이는 제공할 수 없습니다. wallet은 독립형 간편결제(Cash App, Amazon Pay)입니다. bnpl은 후불 결제(Klarna, Affirm, Afterpay)입니다. bank_debit은 미국 은행 계좌에서 출금하는 ACH Direct Debit입니다. bank_transfer는 입금 방식입니다. 고객에게 가상계좌 번호가 표시되고, 고객이 자신의 은행에서 자금을 보냅니다.

The two bank rails behave differently from the rest. They settle after the customer finishes, so the payment sits in processing first, for days if the transfer is slow, and bank_debit can reach failed. Both OutlinePay's fee and yours are capped on them, so offering one beside an uncapped method sends the customer to a page asking which they intend to use before the price is fixed.두 은행 결제 수단은 나머지와 다르게 동작합니다. 고객이 결제를 마친 뒤에 정산되므로 결제가 먼저 processing에 머무르며, 이체가 늦으면 며칠간 지속될 수 있고, bank_debit은 failed에 도달할 수 있습니다. OutlinePay 수수료와 귀사 수수료 모두 상한이 적용되므로, 상한 없는 수단과 함께 제공하면 가격이 확정되기 전에 고객이 사용할 수단을 묻는 페이지가 표시됩니다.

bank_transfer additionally requires customer.email at creation (the virtual account number and any refund follow a named buyer, and the same buyer keeps the same account number across payments), cannot be offered on a payment link, and is available to US merchants only for now. See "Payment methods" under Conventions.bank_transfer는 추가 조건이 있습니다. 생성 시 customer.email이 필요하고(가상계좌 번호와 환불은 특정 구매자를 따라가며, 같은 구매자는 결제할 때마다 같은 계좌번호를 사용합니다), 결제 링크에서는 제공할 수 없으며, 현재는 미국 가맹점만 이용할 수 있습니다. Conventions의 "Payment methods"를 참고해 주십시오.

Provide an array to offer exactly those categories. Omit the field and you get the default of ["card", "wallet"].배열을 지정하시면 정확히 그 분류만 제공됩니다. 생략하시면 기본값 ["card", "wallet"]이 적용됩니다.

Which of the offered categories this payment will use. Set when the customer answered a choice OutlinePay put to them, which happens on the checkout where their answer is what fixes the fee (a capped bank rail offered alongside an uncapped method). Also set whenever the checkout offered exactly one category.제공된 분류 중 이 결제가 사용할 분류입니다. OutlinePay가 고객에게 던진 질문에 고객이 답했을 때 설정되며, 이는 답이 수수료를 확정하는 체크아웃(상한 있는 은행 수단과 상한 없는 수단을 함께 제공)에서 일어납니다. 분류를 하나만 제공한 체크아웃에서도 설정됩니다.

Null only when several categories that price alike were offered. The customer then picks one on the processor's page after the price is settled, and that choice is not recorded here. Read processor_payment_method for what the processor actually used.가격이 같은 분류 여러 개를 제공했을 때만 null입니다. 이때 고객은 가격이 확정된 뒤 처리사의 페이지에서 하나를 고르며, 그 선택은 여기에 기록되지 않습니다. 처리사가 실제로 사용한 수단은 processor_payment_method를 읽어 주십시오. nullable

One of다음 중 하나
card object

The card that settled this payment, as the processor read it off the card networks. It arrives with the other settlement facts, a moment after the outcome: null on the payment.succeeded event itself, filled on the payment.updated event that follows, like fees.processor. Null forever on a payment no card settled, such as a bank rail or a payment that expired unpaid.이 결제를 정산한 카드 정보로, 처리사가 카드 네트워크에서 읽어 온 값입니다. 다른 정산 사실들과 함께 결과 직후에 도착합니다. payment.succeeded 이벤트 시점에는 아직 null이고, fees.processor와 마찬가지로 뒤따르는 payment.updated 이벤트에서 채워집니다. 은행 결제나 미결제 만료처럼 카드로 정산되지 않은 결제에서는 영구히 null입니다.

A wallet payment is a card underneath, so it appears here too, with wallet naming which wallet presented it. A payment whose processor_payment_method reads link stays null, because the processor does not reveal the card behind its own wallet.간편결제도 내부적으로는 카드 결제이므로 여기에 함께 표시되며, 어느 지갑이 카드를 제시했는지는 wallet에 담깁니다. processor_payment_method가 "link"인 결제는 null로 유지됩니다. 처리사가 자사 지갑 뒤의 카드를 공개하지 않기 때문입니다. nullable
card.brand string

The card's scheme, as the networks name it: visa, mastercard, amex, discover, jcb, unionpay and more. A string, not an enum, so a new scheme appears as soon as the processor reports one.카드 네트워크가 부르는 대로의 카드 브랜드입니다. visa, mastercard, amex, discover, jcb, unionpay 등이 있습니다. enum이 아니라 문자열이므로, 처리사가 새 브랜드를 보고하는 즉시 나타납니다. nullable
card.network string

The network the charge was actually routed over. Matches brand on almost every card. The two differ on a co-badged card, which carries two schemes and lets the processor pick the route.결제가 실제로 라우팅된 네트워크입니다. 거의 모든 카드에서 brand와 일치합니다. 두 브랜드를 함께 탑재해 처리사가 경로를 선택하는 겸용(co-badged) 카드에서만 달라집니다. nullable
card.funding string

How the card draws money: credit, debit, prepaid, or unknown.카드의 자금 방식입니다. credit, debit, prepaid, unknown 중 하나입니다. nullable
card.last4 string

The last four digits of the card number. The full number never reaches OutlinePay or you.카드 번호의 마지막 네 자리입니다. 전체 번호는 OutlinePay에도 귀사에도 전달되지 않습니다. nullable
card.exp_month integer

Expiration month, 1 through 12.유효기간의 월로, 1부터 12까지입니다. nullable
card.exp_year integer

Expiration year, four digits.유효기간의 연도로, 네 자리입니다. nullable
card.country string

Two-letter ISO code of the country the card was issued in.카드 발급 국가의 두 글자 ISO 코드입니다. nullable
card.authorization_code string

The approval number the issuer returned when it authorized the charge, the same code printed on a card receipt. Quote it when reconciling against card-company records. Null when the network did not return one.발급사가 결제를 승인하며 돌려준 승인번호로, 카드 매출전표에 인쇄되는 것과 같은 번호입니다. 카드사 기록과 대사할 때 이 번호를 사용하십시오. 네트워크가 승인번호를 돌려주지 않은 경우 null입니다. nullable
card.wallet string

Set when a digital wallet presented the card: apple_pay, google_pay, and so on. Null on a plain card payment.간편결제 지갑이 카드를 제시한 경우에 설정됩니다. apple_pay, google_pay 등입니다. 일반 카드 결제에서는 null입니다. nullable
payment_link_id string

Set when the payment came from a link.링크에서 생성된 결제인 경우 설정됩니다. nullable
checkout_url string

Hosted checkout URL. Present while the payment is not yet terminal, which includes processing: a delayed payment's page is where the customer sees what is still outstanding, and they may return to it days later. Null once the payment succeeds, fails or expires.호스팅 체크아웃 URL입니다. 결제가 종료 상태가 아닌 동안 존재하며, processing도 포함됩니다. 지연 결제의 페이지는 고객이 남은 절차를 확인하는 곳이라 며칠 뒤 다시 방문하기도 합니다. 결제가 성공, 실패 또는 만료되면 null이 됩니다. nullable
receipt_url string

The customer-facing receipt: an OutlinePay-owned URL that resolves to the processor's hosted receipt, viewable in a browser and downloadable as a PDF. The document always shows the payment's latest state, refunds included. Appears when the payment succeeds, null before, and never expires.고객용 영수증입니다. OutlinePay가 소유한 URL이며, 방문할 때마다 처리사의 호스팅 영수증으로 연결됩니다. 브라우저에서 조회하고 PDF로 저장할 수 있습니다. 영수증은 항상 결제의 최신 상태를 보여주며 환불 내역도 반영됩니다. 결제가 성공하면 나타나고 그 전에는 null이며, 만료되지 않습니다. nullable
invoice object

Whether this payment asked the processor for an invoice. Always present, {"enabled": false} when you did not ask, so off and never-asked read the same. Fixed at creation.이 결제가 결제 처리사에 인보이스 발행을 요청했는지 여부입니다. 항상 제공되며, 요청하지 않으신 경우 {"enabled": false}이므로 요청하지 않은 경우와 꺼 두신 경우가 동일하게 표시됩니다. 결제 생성 시점에 확정됩니다.
invoice.enabled boolean
localized_pricing object

Whether the processor was allowed to present the price in the customer's own currency. Always present, {"enabled": false} when you did not ask, so off and never-asked read the same. Fixed at creation.결제 처리사가 고객의 통화로 가격을 표시하도록 허용했는지 여부입니다. 항상 포함되며, 요청하지 않으셨다면 {"enabled": false}이므로 끄신 경우와 요청하지 않으신 경우가 같게 읽힙니다. 생성 시점에 고정됩니다.
localized_pricing.enabled boolean
presentment object

What the customer was actually charged when the processor presented the price in their own currency: amount in that currency's minor unit, and currency. Only on a payment created with localized_pricing.enabled, and only when the customer took the converted price rather than paying in currency. Null otherwise, and null until the charge is read, which is the same payment.updated that fills fees.processor and card.결제 처리사가 고객의 통화로 가격을 표시했을 때 고객에게 실제로 청구된 금액입니다. 해당 통화의 최소 단위 기준 amount와 currency로 구성됩니다. localized_pricing.enabled로 생성된 결제에서, 고객이 currency로 결제하지 않고 환산된 금액을 선택한 경우에만 담깁니다. 그 외에는 null이며, 결제 건을 읽기 전까지도 null입니다. fees.processor와 card가 채워지는 것과 같은 payment.updated에 담겨 도착합니다.

The merchant still receives amount in currency. The difference between the two is the processor's conversion, paid by the customer. What the customer's own bank does after that is not visible to anyone.가맹점은 그대로 currency로 amount를 받습니다. 두 금액의 차이는 결제 처리사의 환전분이며 고객이 부담합니다. 그 이후 고객의 은행이 처리하는 내용은 누구도 확인할 수 없습니다. nullable
presentment.amount integer
presentment.currency string
invoice_url string

The invoice, on a payment created with invoice.enabled: an OutlinePay-owned URL that resolves to the processor's hosted invoice, viewable in a browser and downloadable as a PDF. It is the merchant's own document, issued under their business details, and it shows the payment's latest state including refunds.invoice.enabled로 생성된 결제의 인보이스입니다. OutlinePay가 소유한 URL이며, 처리사의 호스팅 인보이스로 연결됩니다. 브라우저에서 조회하고 PDF로 저장할 수 있습니다. 가맹점 명의로 발행되는 가맹점 자신의 문서이며, 환불 내역을 포함해 결제의 최신 상태를 보여줍니다.

Appears when the payment succeeds, null before, and null forever on a payment that did not ask for one. receipt_url is proof that money moved, while this is the itemised document a buyer's accounting asks for. What it cost the merchant is fees.invoice.결제가 성공하면 나타나고 그 전에는 null이며, 인보이스를 요청하지 않은 결제에서는 계속 null입니다. receipt_url은 금액이 이동했다는 증빙이고, 이 문서는 구매자의 회계에서 요구하는 상세 문서입니다. 가맹점이 부담한 금액은 fees.invoice에 있습니다. nullable
expires_at string

ISO 8601 UTC. When the *checkout session* lapses, not the payment. The window is set by the processor when the session is minted. For Stripe-hosted checkout that is 24 hours after creation. A payment still awaiting_payment at that moment expires.ISO 8601 UTC 형식입니다. 결제가 아니라 *체크아웃 세션*이 만료되는 시각입니다. 기간은 세션 발급 시 처리사가 정하며, Stripe 호스팅 체크아웃은 생성 후 24시간입니다. 이 시각까지 awaiting_payment인 결제는 만료됩니다.

A payment in processing has already been paid for, so this is often in the past on a healthy payment.processing인 결제는 이미 결제가 이루어진 것이므로, 정상적인 결제에서도 이 값이 과거인 경우가 흔합니다. nullable
processing_at string

ISO 8601 UTC. When the customer finished and the payment entered processing. Only delayed methods reach this state.ISO 8601 UTC 형식입니다. 고객이 결제를 마치고 결제가 processing에 들어간 시각입니다. 지연 수단만 이 상태에 도달합니다. nullable
succeeded_at string nullable
funds_available_at string

ISO 8601 UTC, e.g. 2026-09-17T00:00:00Z. The date this payment's net enters the merchant's balance at the processor. No payout happens on this date, and no money arrives in the merchant's bank account on it. What follows is set by the merchant's own payout schedule: on a manual schedule the merchant can request a payout of that amount from this date and not before, and on an automatic schedule there is no request at all, the amount is swept into whichever scheduled payout comes next on or after it.ISO 8601 UTC 형식입니다. 예: 2026-09-17T00:00:00Z. 이 결제의 정산 금액이 결제 처리사에 있는 가맹점 잔액에 들어오는 날짜입니다. 이 날짜에 지급금이 나가지 않으며, 가맹점의 은행 계좌에 금액이 도착하지도 않습니다. 그 이후는 가맹점이 직접 정하는 지급 주기가 결정합니다. 수동 주기라면 가맹점은 이 날짜부터 그 금액의 지급을 신청할 수 있고 그 전에는 신청할 수 없습니다. 자동 주기라면 신청 절차 자체가 없으며, 이 날짜 이후 처음 도래하는 지급 일정에 그 금액이 포함됩니다.

Null on payment.succeeded and filled by the payment.updated that follows, the same timing as fees.processor. Null forever on a payment that collected nothing, and on any payment that settled before this field existed.payment.succeeded에서는 null이며, 뒤이어 도착하는 payment.updated가 값을 채웁니다. fees.processor와 같은 시점입니다. 회수된 금액이 없는 결제, 그리고 이 필드가 생기기 전에 정산된 결제에서는 계속 null로 남습니다. nullable
failed_at string nullable
expired_at string nullable
failure_reason enum

Why a payment failed, in OutlinePay's vocabulary, translated from the processor's own failure code at the boundary.결제가 실패한 이유로, 처리사의 실패 코드를 경계에서 OutlinePay의 용어로 변환한 값입니다.

insufficient_funds: the account didn't have the money. Retry later, the account itself is fine.insufficient_funds: 계좌에 잔액이 없었습니다. 계좌 자체는 정상이므로 나중에 다시 시도하십시오.

account_closed: the account no longer exists. Ask for different details.account_closed: 계좌가 더 이상 존재하지 않습니다. 다른 계좌 정보를 요청하십시오.

account_details_invalid: the account or routing number was wrong, or a linked account's number was deactivated. Ask for correct details.account_details_invalid: 계좌 번호나 라우팅 번호가 잘못되었거나, 연동 계좌의 번호가 비활성화되었습니다. 올바른 정보를 요청하십시오.

not_authorized: there's no valid authorization to debit this account, usually because the customer disputed an earlier debit. Collect a fresh authorization before trying again.not_authorized: 이 계좌를 출금할 유효한 승인이 없습니다. 대개 고객이 이전 출금에 이의를 제기한 경우입니다. 다시 시도하기 전에 새 승인을 받으십시오.

account_blocked: the customer's bank is refusing debits, frozen or restricted. The customer has to sort it out with their bank.account_blocked: 고객의 은행이 출금을 거부하고 있습니다(동결 또는 제한). 고객이 은행과 직접 해결해야 합니다.

other: the processor gave a reason we don't have a word for, or gave none. Treat it as a failure with no further guidance.other: 처리사가 대응하는 단어가 없는 이유를 제시했거나 이유를 제시하지 않았습니다. 추가 안내가 없는 실패로 처리하십시오.

Why the payment failed, and null unless it did. Only bank rails reach it: a declined card doesn't end the checkout, the customer just tries again on the processor's page, so a card payment goes from awaiting_payment to succeeded or expires.결제가 실패한 이유이며, 실패하지 않았다면 null입니다. 은행 수단만 이 값에 도달합니다. 카드 거절은 체크아웃을 끝내지 않고 고객이 처리사 페이지에서 다시 시도하므로, 카드 결제는 awaiting_payment에서 succeeded로 가거나 만료됩니다.

Grouped by what to do next rather than by the processor's own code. Several of Stripe's ACH codes call for the same action and fold into one value here.처리사의 코드가 아니라 다음에 할 일을 기준으로 묶었습니다. Stripe의 여러 ACH 코드가 같은 조치를 요구하므로 이곳에서는 하나의 값으로 접힙니다. nullable

One of다음 중 하나
payment_methods array<string>

The method categories you restricted this payment to, echoed back. Null means you did not ask, which offers the documented default of ["card", "wallet"], not every method the processor supports.이 결제를 제한하신 수단 분류를 그대로 반환합니다. null은 지정하지 않으셨다는 뜻이며, 이때 처리사가 지원하는 모든 수단이 아니라 문서화된 기본값 ["card", "wallet"]이 제공됩니다. nullable
bank_verification enum

How a customer's bank account must be proven to be theirs before it can be debited. Applies to bank_debit and is ignored on a checkout that offers no bank method.고객의 은행 계좌가 본인 것임을 어떻게 증명해야 출금할 수 있는지입니다. bank_debit에 적용되며, 은행 수단이 없는 체크아웃에서는 무시됩니다.

instant_or_delayed (default): the customer links their bank instantly, or, if they'd rather not or their bank can't be reached, enters the account number and confirms two small deposits instead. That second path takes 1-2 business days for the deposits to arrive and gives them 10 days to enter them, so the payment can sit in processing for a fortnight. Accepts the most customers.instant_or_delayed(기본값): 고객이 은행을 즉시 연동하거나, 원치 않거나 연동되지 않는 은행이면 계좌 번호를 입력하고 소액 입금 2건을 확인합니다. 두 번째 경로는 입금 도착까지 영업일 1~2일이 걸리고 입력 기한이 10일이므로, 결제가 2주가량 processing에 머무를 수 있습니다. 가장 많은 고객을 수용합니다.

instant: instant linking only. You learn within seconds whether the account is good. A customer whose bank cannot be linked this way cannot pay by bank at all.instant: 즉시 연동만 허용합니다. 계좌가 유효한지 몇 초 안에 알 수 있습니다. 이 방식으로 연동되지 않는 은행의 고객은 은행 결제를 아예 사용할 수 없습니다.

Echoed as you sent it. Null means you did not ask, so instant_or_delayed applied.보내신 그대로 반환합니다. null은 지정하지 않으셨다는 뜻이며, instant_or_delayed가 적용되었습니다. nullable

One of다음 중 하나
metadata object

Your own key/value pairs, for correlating this object back to your records. We never interpret the contents: they are stored, returned on every read, and carried on every event this object emits. A payment's, refund's or payment link's is also forwarded to the processor. A merchant's is not. At most 50 pairs, keys up to 40 characters, values up to 500. Values are stored as strings. Keys beginning outlinepay_, plus outline_fee and partner_fee, are reserved by OutlinePay and rejected. Never put secrets here.이 객체를 귀사의 기록과 연결하기 위한 자체 키/값 쌍입니다. OutlinePay는 내용을 해석하지 않습니다. 저장되고, 모든 조회에 반환되며, 이 객체가 발행하는 모든 이벤트에 실립니다. 결제, 환불, 결제 링크의 메타데이터는 결제 처리사에도 전달되며, 가맹점의 메타데이터는 전달되지 않습니다. 최대 50쌍, 키는 40자, 값은 500자까지이며 문자열로 저장됩니다. outlinepay_로 시작하는 키와 outline_fee, partner_fee는 OutlinePay가 예약하고 있어 거부됩니다. 비밀 정보는 절대 넣지 마십시오.
created_at string

ISO 8601 UTC.ISO 8601 UTC 형식입니다.
The Payment objectPayment 객체 
{
  "id": "pay_3Nk8Qh2Lmp7T",
  "object": "payment",
  "status": "awaiting_payment",
  "mode": "test",
  "merchant_id": "mrc_9f2c8bAaZ1kQ",
  "amount": 10000,
  "currency": "usd",
  "description": "Order",
  "customer": {
    "email": "[email protected]"
  },
  "fees": {
    "processor": null,
    "outline": 50,
    "partner": 100,
    "dispute": 0,
    "invoice": null,
    "fraud_screening": null,
    "tax": {
      "invoice": null,
      "fraud_screening": null
    },
    "total": 150
  },
  "merchant_net": 9850,
  "amount_refunded": 0,
  "amount_disputed": 0,
  "amount_refundable": 10000,
  "refunds": [],
  "disputes": [],
  "processor": "stripe",
  "processor_payment_method": null,
  "processor_reference": null,
  "selected_payment_method": null,
  "card": null,
  "bank_verification": null,
  "payment_link_id": null,
  "checkout_url": "https://checkout.outlinepay.com/c/pay_3Nk8Qh2Lmp7T",
  "receipt_url": null,
  "invoice_url": null,
  "localized_pricing": {
    "enabled": false
  },
  "presentment": null,
  "expires_at": "2026-07-22T12:45:00Z",
  "processing_at": null,
  "succeeded_at": null,
  "funds_available_at": null,
  "failed_at": null,
  "expired_at": null,
  "failure_reason": null,
  "created_at": "2026-07-21T12:45:00Z"
}

POST /v1/payments

Create a payment결제 생성

Creation is never a payment outcome. The response is status awaiting_payment plus an OutlinePay-owned checkout_url. Whoever opens it completes the payment on the processor's hosted page. The terminal state (succeeded/failed/expired) arrives by webhook, with Retrieve a payment as the polling fallback. Point success_url and cancel_url at endpoints you control. The redirect is navigation, not proof of payment.결제 생성은 결제 결과가 아닙니다. 응답은 status가 awaiting_payment인 상태와 OutlinePay가 소유한 checkout_url이며, 이 주소를 여는 사람이 결제 처리사의 호스팅 페이지에서 결제를 완료합니다. 최종 상태(succeeded/failed/expired)는 웹훅으로 전달되고, 결제 조회가 폴링 대체 수단입니다. success_url과 cancel_url은 귀사가 관리하는 엔드포인트로 지정해 주십시오. 리디렉션은 화면 이동일 뿐 결제가 완료되었다는 증거가 아닙니다.

Onboarding required온보딩 필수
The merchant must have finished onboarding before you can charge it. Until the processor verifies the account this returns 409 merchant_not_onboarded and no payment is created. Put the merchant through Create an account session first. Its status turns active and we emit merchant.updated when it can take money.결제를 요청하시려면 가맹점이 온보딩을 마쳐야 합니다. 결제 처리사가 계정을 검증하기 전까지는 409 merchant_not_onboarded가 반환되며 결제는 생성되지 않습니다. 먼저 계정 세션 생성으로 가맹점의 온보딩을 진행해 주십시오. 결제가 가능해지면 status가 active로 바뀌고 merchant.updated 이벤트를 발송합니다.

Conventions규약 Onboarding is required before charging결제 전 온보딩 필수·Payment methods결제 수단·When each fee arrives각 수수료가 도착하는 시점

Request body요청 본문

Field필드 Type타입 Description설명
merchant_id
required 		string
amount
required 		integer

Minor units of currency (for usd, cents). The minimum charge is 100 ($1.00): a lower amount is refused as a 400 invalid_request naming amount, before the processor is called.currency의 최소 단위 정수입니다(usd는 센트). 최소 결제 금액은 100($1.00)이며, 그보다 작은 금액은 처리사를 호출하기 전에 amount를 지목한 400 invalid_request로 거부됩니다.
currency
optional 		enum

What the customer is charged in, as distinct from what the merchant is paid in, unless you turn on localized_pricing. usd is the only value we accept today, and it is the default, so you can leave it out. Contact us if you need another.고객에게 청구되는 통화이며, 가맹점이 지급받는 통화와 구분됩니다. 다만 localized_pricing을 켜시면 예외입니다. 현재 허용되는 값은 usd뿐이고 기본값이므로 생략하셔도 됩니다. 다른 통화가 필요하시면 문의해 주십시오.

One of다음 중 하나
description
optional 		string
customer
optional 		object

Who is paying. Required (with email) whenever payment_methods includes bank_transfer, optional otherwise. The email keys the buyer's identity, so repeat buyers keep the same virtual account number.누가 결제하는지입니다. payment_methods에 bank_transfer가 포함될 때는 (email과 함께) 필수이고, 그 외에는 선택입니다. 이메일이 구매자의 식별자가 되므로, 같은 구매자는 결제할 때마다 같은 가상계좌 번호를 사용합니다.
customer.email
optional 		string
success_url
required 		string

Where the processor sends the browser after payment.결제 후 처리사가 브라우저를 보내는 곳입니다.
cancel_url
optional 		string

Where the processor sends the browser on cancel.취소 시 처리사가 브라우저를 보내는 곳입니다.
processor
optional 		string

Which rail to charge on. Defaults to the merchant's default processor.결제에 사용할 경로입니다. 기본값은 가맹점의 기본 처리사입니다.
payment_methods
optional 		array<string>

Restrict the checkout to these method categories (an allow-list). Omit for the documented default, ["card", "wallet"]. Naming bank_transfer requires customer.email.체크아웃을 이 수단 분류로 제한합니다(허용 목록). 생략하시면 문서화된 기본값 ["card", "wallet"]이 적용됩니다. bank_transfer를 지정하려면 customer.email이 필요합니다.
bank_verification
optional 		enum

How a customer's bank account must be proven to be theirs before it can be debited. Applies to bank_debit and is ignored on a checkout that offers no bank method.고객의 은행 계좌가 본인 것임을 어떻게 증명해야 출금할 수 있는지입니다. bank_debit에 적용되며, 은행 수단이 없는 체크아웃에서는 무시됩니다.

instant_or_delayed (default): the customer links their bank instantly, or, if they'd rather not or their bank can't be reached, enters the account number and confirms two small deposits instead. That second path takes 1-2 business days for the deposits to arrive and gives them 10 days to enter them, so the payment can sit in processing for a fortnight. Accepts the most customers.instant_or_delayed(기본값): 고객이 은행을 즉시 연동하거나, 원치 않거나 연동되지 않는 은행이면 계좌 번호를 입력하고 소액 입금 2건을 확인합니다. 두 번째 경로는 입금 도착까지 영업일 1~2일이 걸리고 입력 기한이 10일이므로, 결제가 2주가량 processing에 머무를 수 있습니다. 가장 많은 고객을 수용합니다.

instant: instant linking only. You learn within seconds whether the account is good. A customer whose bank cannot be linked this way cannot pay by bank at all.instant: 즉시 연동만 허용합니다. 계좌가 유효한지 몇 초 안에 알 수 있습니다. 이 방식으로 연동되지 않는 은행의 고객은 은행 결제를 아예 사용할 수 없습니다.

Only meaningful when the checkout offers bank_debit. Omit it and you get instant_or_delayed.체크아웃이 bank_debit을 제공할 때만 의미가 있습니다. 생략하시면 instant_or_delayed가 적용됩니다.

One of다음 중 하나
invoice
optional 		object

Ask the payment processor to issue an invoice once this payment succeeds. Off unless you send it, because the processor charges the merchant per invoice. It cannot be added after the payment is created. The finished document is invoice_url on the payment, and what it cost the merchant is fees.invoice.결제가 성공하면 결제 처리사가 인보이스를 발행하도록 요청합니다. 보내지 않으면 꺼져 있습니다. 처리사가 인보이스 건당 가맹점에 수수료를 부과하기 때문입니다. 결제가 생성된 뒤에는 추가할 수 없습니다. 완성된 문서는 결제의 invoice_url에 있고, 가맹점이 부담한 금액은 fees.invoice에 있습니다.
invoice.enabled
optional 		boolean

Must be true or false. Anything else is refused.true 또는 false여야 합니다. 그 외의 값은 거부합니다.
localized_pricing
optional 		object

Let the payment processor present the price in the customer's own currency when they are outside the US. Off unless you send it: the converted figure the customer sees includes the processor's conversion fee, 2 to 4% with Stripe, paid by the customer, and the customer can still choose to pay in currency. The merchant receives amount in currency either way, and the payment then records what the customer paid as presentment. Fixed at creation.고객이 미국 밖에 있을 때 결제 처리사가 가격을 고객의 통화로 표시하도록 허용합니다. 보내지 않으시면 꺼져 있습니다. 고객이 보는 환산 금액에는 처리사의 환전 수수료(Stripe 기준 2~4%)가 포함되어 고객이 부담하며, 고객은 여전히 currency로 결제하는 쪽을 선택할 수 있습니다. 가맹점은 어느 경우든 currency로 amount를 받고, 결제 객체에는 고객이 실제로 결제한 금액이 presentment로 기록됩니다. 생성 시점에 고정됩니다.
localized_pricing.enabled
optional 		boolean

Must be true or false. Anything else is refused.true 또는 false여야 합니다. 그 외의 값은 거부합니다.
metadata
optional 		object

Your own key/value pairs, for correlating this object back to your records. We never interpret the contents: they are stored, returned on every read, and carried on every event this object emits. A payment's, refund's or payment link's is also forwarded to the processor. A merchant's is not. At most 50 pairs, keys up to 40 characters, values up to 500. Values are stored as strings. Keys beginning outlinepay_, plus outline_fee and partner_fee, are reserved by OutlinePay and rejected. Never put secrets here.이 객체를 귀사의 기록과 연결하기 위한 자체 키/값 쌍입니다. OutlinePay는 내용을 해석하지 않습니다. 저장되고, 모든 조회에 반환되며, 이 객체가 발행하는 모든 이벤트에 실립니다. 결제, 환불, 결제 링크의 메타데이터는 결제 처리사에도 전달되며, 가맹점의 메타데이터는 전달되지 않습니다. 최대 50쌍, 키는 40자, 값은 500자까지이며 문자열로 저장됩니다. outlinepay_로 시작하는 키와 outline_fee, partner_fee는 OutlinePay가 예약하고 있어 거부됩니다. 비밀 정보는 절대 넣지 마십시오.

Example request요청 예시

<?php
$ch = curl_init("https://api.outlinepay.com/v1/payments");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer olp_sk_test_YOUR_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "merchant_id" => "mrc_9f2c8bAaZ1kQ",
        "amount"      => 10000,
        "currency"    => "usd",
        "description" => "Order",
        "customer"    => [
            "email" => "[email protected]",
        ],
        "success_url" => "https://pg.cookiepay.example/op/result",
        "cancel_url"  => "https://pg.cookiepay.example/op/cancel",
    ]),
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Response응답

Returns a Payment.Payment 객체를 반환합니다.

Response응답 · 200 
{
  "id": "pay_3Nk8Qh2Lmp7T",
  "object": "payment",
  "status": "awaiting_payment",
  "mode": "test",
  "merchant_id": "mrc_9f2c8bAaZ1kQ",
  "amount": 10000,
  "currency": "usd",
  "description": "Order",
  "customer": {
    "email": "[email protected]"
  },
  "fees": {
    "processor": null,
    "outline": 50,
    "partner": 100,
    "dispute": 0,
    "invoice": null,
    "fraud_screening": null,
    "tax": {
      "invoice": null,
      "fraud_screening": null
    },
    "total": 150
  },
  "merchant_net": 9850,
  "amount_refunded": 0,
  "amount_disputed": 0,
  "amount_refundable": 10000,
  "refunds": [],
  "disputes": [],
  "processor": "stripe",
  "processor_payment_method": null,
  "processor_reference": null,
  "selected_payment_method": null,
  "card": null,
  "bank_verification": null,
  "payment_link_id": null,
  "checkout_url": "https://checkout.outlinepay.com/c/pay_3Nk8Qh2Lmp7T",
  "receipt_url": null,
  "invoice_url": null,
  "localized_pricing": {
    "enabled": false
  },
  "presentment": null,
  "expires_at": "2026-07-22T12:45:00Z",
  "processing_at": null,
  "succeeded_at": null,
  "funds_available_at": null,
  "failed_at": null,
  "expired_at": null,
  "failure_reason": null,
  "created_at": "2026-07-21T12:45:00Z"
}

GET /v1/payments

List payments결제 목록 조회

Your payments, newest first. Filter by merchant_id, status and creation time.귀사의 결제를 최신순으로 반환합니다. merchant_id, status, 생성 시각으로 필터링하실 수 있습니다.

Parameters파라미터

Parameter파라미터 In위치 Type타입 Description설명
merchant_id
optional 		query string

Only payments for this merchant.이 가맹점의 결제만 반환합니다.
status
optional 		query enum

Where the payment is. Both lifecycles are drawn under The Payment object.결제가 어느 단계에 있는지입니다. 두 상태 흐름 모두 The Payment object 아래에 그림으로 정리되어 있습니다.

awaiting_payment: the customer has not finished. A declined card does not end this state. The customer retries on the checkout page.awaiting_payment: 고객이 아직 결제를 마치지 않았습니다. 카드 승인 거절은 이 상태를 끝내지 않습니다. 고객이 체크아웃 페이지에서 다시 시도합니다.

processing: the customer has paid but the money is still moving. Only delayed methods (bank_debit, bank_transfer) reach it, it can last days, and nothing is decided yet, so do not fulfill on it.processing: 고객은 결제했지만 자금이 아직 이동 중입니다. 지연 정산 수단(bank_debit, bank_transfer)만 이 상태에 도달하며, 며칠간 지속될 수 있고 아직 아무것도 확정되지 않았으므로 이 상태에서 상품을 발송하지 마십시오.

failed: reachable only from processing, so only on delayed methods. failure_reason says why.failed: processing에서만 도달하므로 지연 정산 수단에서만 발생합니다. 원인은 failure_reason에 담깁니다.

Only payments in this state.이 상태의 결제만 반환합니다.

One of다음 중 하나
created_after
optional 		query string

Only records whose created_at is at or after this ISO 8601 timestamp or date. Inclusive.created_at이 이 ISO 8601 시각 또는 날짜 이후(같은 시각 포함)인 항목만 반환합니다.
created_before
optional 		query string

Only records whose created_at is before this ISO 8601 timestamp or date. Exclusive, so a month's created_before is the next month's created_after.created_at이 이 ISO 8601 시각 또는 날짜 이전인 항목만 반환합니다. 같은 시각은 제외되므로, 한 달의 created_before가 다음 달의 created_after가 됩니다.
limit
optional 		query integer

Page size, 1–100 (default 20).페이지 크기이며 1~100(기본값 20)입니다.
starting_after
optional 		query string

A resource id. Returns records after it (newest-first cursor).리소스 id이며, 그 이후의 레코드를 반환합니다(최신순 커서).

Example request요청 예시

<?php
$ch = curl_init("https://api.outlinepay.com/v1/payments?merchant_id=mrc_9f2c8bAaZ1kQ&created_after=2026-08-01T00:00:00Z&created_before=2026-09-01T00:00:00Z&limit=20");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer olp_sk_test_YOUR_KEY",
    ],
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Response응답

Returns a page of Payment objects: { "data": [...], "has_more": bool }.Payment 객체의 목록 페이지를 반환합니다: { "data": [...], "has_more": bool }.

GET /v1/payments/{id}

Retrieve a payment결제 조회

The authoritative status of a payment, the polling fallback to the webhook.결제의 기준 상태이며, 웹훅에 대한 폴링 대체 수단입니다.

Conventions규약 When each fee arrives각 수수료가 도착하는 시점·A dispute does not un-settle a payment분쟁은 결제 상태를 되돌리지 않습니다

Parameters파라미터

Parameter파라미터 In위치 Type타입 Description설명
id
required 		path string

The payment id.결제 id입니다.

Example request요청 예시

<?php
$ch = curl_init("https://api.outlinepay.com/v1/payments/pay_3Nk8Qh2Lmp7T");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer olp_sk_test_YOUR_KEY",
    ],
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Response응답

Returns a Payment.Payment 객체를 반환합니다.

Response응답 · 200 
{
  "id": "pay_3Nk8Qh2Lmp7T",
  "object": "payment",
  "status": "awaiting_payment",
  "mode": "test",
  "merchant_id": "mrc_9f2c8bAaZ1kQ",
  "amount": 10000,
  "currency": "usd",
  "description": "Order",
  "customer": {
    "email": "[email protected]"
  },
  "fees": {
    "processor": null,
    "outline": 50,
    "partner": 100,
    "dispute": 0,
    "invoice": null,
    "fraud_screening": null,
    "tax": {
      "invoice": null,
      "fraud_screening": null
    },
    "total": 150
  },
  "merchant_net": 9850,
  "amount_refunded": 0,
  "amount_disputed": 0,
  "amount_refundable": 10000,
  "refunds": [],
  "disputes": [],
  "processor": "stripe",
  "processor_payment_method": null,
  "processor_reference": null,
  "selected_payment_method": null,
  "card": null,
  "bank_verification": null,
  "payment_link_id": null,
  "checkout_url": "https://checkout.outlinepay.com/c/pay_3Nk8Qh2Lmp7T",
  "receipt_url": null,
  "invoice_url": null,
  "localized_pricing": {
    "enabled": false
  },
  "presentment": null,
  "expires_at": "2026-07-22T12:45:00Z",
  "processing_at": null,
  "succeeded_at": null,
  "funds_available_at": null,
  "failed_at": null,
  "expired_at": null,
  "failure_reason": null,
  "created_at": "2026-07-21T12:45:00Z"
}

Object객체

The Refund objectRefund 객체

Return money for a succeeded payment, in full or in part.완료된(succeeded) 결제의 대금을 전액 또는 부분 반환합니다.

Refunds need no special test values: refund any succeeded test payment. For the one test-mode limitation (bank transfers), see Testing · Refunds.환불에는 별도의 테스트 값이 없으며, 성공한 테스트 결제를 환불하면 됩니다. 테스트 모드의 한 가지 제약(계좌 이체)은 테스트 · 환불 섹션을 참고해 주십시오.

Field필드 Type타입 Description설명
id string
object string

The literal string refund.고정 문자열 refund입니다.
status enum

failed also covers a refund the processor withdrew rather than refused, so the two are told apart by failure_reason, not by the status.failed에는 처리사가 거절한 환불뿐 아니라 철회한 환불도 포함됩니다. 둘은 상태가 아니라 failure_reason으로 구분하십시오.

One of다음 중 하나
mode enum

The world this object lives in, test (sandbox) or live. Matches your API key's prefix (olp_sk_test_ / olp_sk_live_).이 객체가 속한 환경으로, test(샌드박스) 또는 live입니다. API 키의 접두사(olp_sk_test_ / olp_sk_live_)와 일치합니다.

One of다음 중 하나
payment_id string
merchant_id string
processor string

The rail this refund settled on, e.g. stripe. Inherited from the payment.이 환불이 정산된 경로입니다. 예: stripe. 결제에서 물려받습니다.
amount integer
failure_reason enum

Why a refund did not reach the customer, in OutlinePay's vocabulary, translated from the processor's own failure code at the boundary. Null unless the refund failed.환불이 고객에게 도달하지 못한 이유로, 처리사의 실패 코드를 경계에서 OutlinePay의 용어로 변환한 값입니다. 환불이 실패하지 않았다면 null입니다.

card_unusable: the card can't be refunded to. It was reported lost or stolen, or it's expired or canceled. Refund the customer another way, retrying will fail again.card_unusable: 해당 카드로는 환불할 수 없습니다. 분실이나 도난으로 신고되었거나, 만료 또는 해지된 카드입니다. 다시 시도해도 실패하므로 다른 방법으로 환불하십시오.

insufficient_funds: the merchant's balance didn't have enough to cover the refund. Retry after it funds.insufficient_funds: 가맹점 잔액이 환불액에 미치지 못했습니다. 잔액이 채워진 뒤 다시 시도하십시오.

declined: the card issuer declined the refund. Retry once, then refund another way if it declines again.declined: 카드 발급사가 환불을 거절했습니다. 한 번 다시 시도하고, 또 거절되면 다른 방법으로 환불하십시오.

disputed: the charge is under dispute. Do not retry, the dispute governs this refund now.disputed: 해당 결제가 분쟁 중입니다. 이제 이 환불은 분쟁 절차를 따르므로 다시 시도하지 마십시오.

canceled: the refund was withdrawn, not refused. Nothing to retry, create a new refund if one is still owed.canceled: 환불이 거절된 것이 아니라 철회되었습니다. 다시 시도할 것은 없으며, 환불이 여전히 필요하다면 새 환불을 생성하십시오.

other: the processor gave a reason we don't have a word for, or gave none. Treat it as a failure with no further guidance.other: 처리사가 대응하는 단어가 없는 이유를 제시했거나 이유를 제시하지 않았습니다. 추가 안내가 없는 실패로 처리하십시오. nullable

One of다음 중 하나
metadata object

Your own key/value pairs, for correlating this object back to your records. We never interpret the contents: they are stored, returned on every read, and carried on every event this object emits. A payment's, refund's or payment link's is also forwarded to the processor. A merchant's is not. At most 50 pairs, keys up to 40 characters, values up to 500. Values are stored as strings. Keys beginning outlinepay_, plus outline_fee and partner_fee, are reserved by OutlinePay and rejected. Never put secrets here.이 객체를 귀사의 기록과 연결하기 위한 자체 키/값 쌍입니다. OutlinePay는 내용을 해석하지 않습니다. 저장되고, 모든 조회에 반환되며, 이 객체가 발행하는 모든 이벤트에 실립니다. 결제, 환불, 결제 링크의 메타데이터는 결제 처리사에도 전달되며, 가맹점의 메타데이터는 전달되지 않습니다. 최대 50쌍, 키는 40자, 값은 500자까지이며 문자열로 저장됩니다. outlinepay_로 시작하는 키와 outline_fee, partner_fee는 OutlinePay가 예약하고 있어 거부됩니다. 비밀 정보는 절대 넣지 마십시오.
created_at string
The Refund objectRefund 객체 
{
  "id": "re_5Fp1Xy8nQd2W",
  "object": "refund",
  "status": "pending",
  "mode": "test",
  "payment_id": "pay_3Nk8Qh2Lmp7T",
  "merchant_id": "mrc_9f2c8bAaZ1kQ",
  "amount": 2500,
  "created_at": "2026-07-21T12:10:00Z"
}

POST /v1/refunds

Create a refund환불 생성

Refunds a succeeded payment. Usually pending here and resolved by the refund.completed / refund.failed webhook. The platform fee is not returned.완료된(succeeded) 결제를 환불합니다. 보통 이 시점에는 처리 중 상태이며 refund.completed 또는 refund.failed 웹훅으로 확정됩니다. 플랫폼 수수료는 반환되지 않습니다.

Amount is in the smallest currency unit금액은 해당 통화의 최소 단위입니다
An integer, like every amount in this API: 2500 is $25.00 and 1 is one cent. Omit it to refund the payment's amount_refundable, which is what is still owed, not its amount. Several partial refunds are allowed as long as they add up to no more than that.이 API의 모든 금액과 마찬가지로 정수입니다. 2500은 25.00달러이고 1은 1센트입니다. 생략하시면 결제의 amount_refundable, 즉 amount가 아니라 아직 남은 금액을 환불합니다. 합계가 그 금액을 넘지 않는 한 부분 환불을 여러 번 하실 수 있습니다.
Only succeeded payments완료된 결제만 환불할 수 있습니다
A payment that never succeeded refuses with 400 invalid_request. A fully refunded payment has amount_refundable 0 and refuses the same way.완료되지 않은 결제는 400 invalid_request로 거부합니다. 이미 전액 환불된 결제는 amount_refundable이 0이며 동일하게 거부됩니다.

Conventions규약 A dispute does not un-settle a payment분쟁은 결제 상태를 되돌리지 않습니다

Emits이벤트 발행 refund.completed

Idempotency-Key

This endpoint requires an Idempotency-Key request header. A double-fired refund would move money twice.이 엔드포인트에는 Idempotency-Key 요청 헤더가 필수입니다. 환불이 중복 실행되면 자금이 두 번 이동하기 때문입니다.

How to generate and reuse a key키를 생성하고 재사용하는 방법

Request body요청 본문

Field필드 Type타입 Description설명
payment_id
required 		string
amount
optional 		integer

Omit to refund what is still refundable.생략하시면 남은 환불 가능 금액이 모두 환불됩니다.
metadata
optional 		object

Your own key/value pairs, for correlating this object back to your records. We never interpret the contents: they are stored, returned on every read, and carried on every event this object emits. A payment's, refund's or payment link's is also forwarded to the processor. A merchant's is not. At most 50 pairs, keys up to 40 characters, values up to 500. Values are stored as strings. Keys beginning outlinepay_, plus outline_fee and partner_fee, are reserved by OutlinePay and rejected. Never put secrets here.이 객체를 귀사의 기록과 연결하기 위한 자체 키/값 쌍입니다. OutlinePay는 내용을 해석하지 않습니다. 저장되고, 모든 조회에 반환되며, 이 객체가 발행하는 모든 이벤트에 실립니다. 결제, 환불, 결제 링크의 메타데이터는 결제 처리사에도 전달되며, 가맹점의 메타데이터는 전달되지 않습니다. 최대 50쌍, 키는 40자, 값은 500자까지이며 문자열로 저장됩니다. outlinepay_로 시작하는 키와 outline_fee, partner_fee는 OutlinePay가 예약하고 있어 거부됩니다. 비밀 정보는 절대 넣지 마십시오.

Example request요청 예시

<?php
// Mint once per refund, store it, resend the same value on every retry.
$idempotencyKey = bin2hex(random_bytes(16));

$ch = curl_init("https://api.outlinepay.com/v1/refunds");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer olp_sk_test_YOUR_KEY",
        "Idempotency-Key: " . $idempotencyKey,
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "payment_id" => "pay_3Nk8Qh2Lmp7T",
        "amount"     => 2500,
    ]),
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Response응답

Returns a Refund.Refund 객체를 반환합니다.

Response응답 · 200 
{
  "id": "re_5Fp1Xy8nQd2W",
  "object": "refund",
  "status": "pending",
  "mode": "test",
  "payment_id": "pay_3Nk8Qh2Lmp7T",
  "merchant_id": "mrc_9f2c8bAaZ1kQ",
  "amount": 2500,
  "created_at": "2026-07-21T12:10:00Z"
}

GET /v1/refunds

List refunds환불 목록 조회

Your refunds across every payment, newest first. A payment already carries its own refunds inline, so use this when you do not start from a payment, such as reconciling a day's returns. Filter by merchant_id, payment_id, status and creation time.모든 결제에 걸친 환불 내역이며 최신순입니다. 결제 객체에는 이미 해당 결제의 환불이 함께 담겨 있으므로, 하루치 환불을 대사하는 경우처럼 결제 건에서 출발하지 않을 때 이 엔드포인트를 사용하십시오. merchant_id, payment_id, status, 생성 시각으로 필터링하실 수 있습니다.

Two views of the same refund같은 환불을 보는 두 가지 방식
A payment's refunds[] array is the lean view (id, status, amount, metadata, created_at). This endpoint returns the full Refund object, which additionally names its payment, merchant, mode and processor. The ids match, so either can be followed to the other.결제의 refunds[] 배열은 간략형(id, status, amount, metadata, created_at)입니다. 이 엔드포인트는 전체 Refund 객체를 반환하며, 결제와 가맹점, 모드, 결제 처리사를 함께 담습니다. id가 서로 같으므로 어느 쪽에서든 다른 쪽으로 이동하실 수 있습니다.

Parameters파라미터

Parameter파라미터 In위치 Type타입 Description설명
merchant_id
optional 		query string

Only refunds of this merchant's payments.이 가맹점의 결제에 대한 환불만 반환합니다.
payment_id
optional 		query string

Only refunds against this payment.이 결제에 대한 환불만 반환합니다.
status
optional 		query enum

failed also covers a refund the processor withdrew rather than refused, so the two are told apart by failure_reason, not by the status.failed에는 처리사가 거절한 환불뿐 아니라 철회한 환불도 포함됩니다. 둘은 상태가 아니라 failure_reason으로 구분하십시오.

Only refunds in this state.이 상태의 환불만 반환합니다.

One of다음 중 하나
created_after
optional 		query string

Only records whose created_at is at or after this ISO 8601 timestamp or date. Inclusive.created_at이 이 ISO 8601 시각 또는 날짜 이후(같은 시각 포함)인 항목만 반환합니다.
created_before
optional 		query string

Only records whose created_at is before this ISO 8601 timestamp or date. Exclusive, so a month's created_before is the next month's created_after.created_at이 이 ISO 8601 시각 또는 날짜 이전인 항목만 반환합니다. 같은 시각은 제외되므로, 한 달의 created_before가 다음 달의 created_after가 됩니다.
limit
optional 		query integer

Page size, 1–100 (default 20).페이지 크기이며 1~100(기본값 20)입니다.
starting_after
optional 		query string

A resource id. Returns records after it (newest-first cursor).리소스 id이며, 그 이후의 레코드를 반환합니다(최신순 커서).

Example request요청 예시

<?php
$ch = curl_init("https://api.outlinepay.com/v1/refunds?merchant_id=mrc_9f2c8bAaZ1kQ&payment_id=pay_3Nk8Qh2Lmp7T&created_after=2026-08-01T00:00:00Z&created_before=2026-09-01T00:00:00Z&limit=20");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer olp_sk_test_YOUR_KEY",
    ],
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Response응답

Returns a page of Refund objects: { "data": [...], "has_more": bool }.Refund 객체의 목록 페이지를 반환합니다: { "data": [...], "has_more": bool }.

GET /v1/refunds/{id}

Retrieve a refund환불 조회

The authoritative state of a refund, the polling fallback to the webhook.환불의 기준 상태이며, 웹훅에 대한 폴링 대체 수단입니다.

Parameters파라미터

Parameter파라미터 In위치 Type타입 Description설명
id
required 		path string

The refund id.환불 id입니다.

Example request요청 예시

<?php
$ch = curl_init("https://api.outlinepay.com/v1/refunds/re_5Fp1Xy8nQd2W");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer olp_sk_test_YOUR_KEY",
    ],
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Response응답

Returns a Refund.Refund 객체를 반환합니다.

Response응답 · 200 
{
  "id": "re_5Fp1Xy8nQd2W",
  "object": "refund",
  "status": "pending",
  "mode": "test",
  "payment_id": "pay_3Nk8Qh2Lmp7T",
  "merchant_id": "mrc_9f2c8bAaZ1kQ",
  "amount": 2500,
  "created_at": "2026-07-21T12:10:00Z"
}

Object객체

The Dispute objectDispute 객체

Chargebacks a cardholder opened with their bank. Read-only. Evidence is submitted by the merchant in the processor's embedded component.카드 소지자가 은행에 제기한 지불 거절입니다. 읽기 전용이며, 증빙은 가맹점이 결제 처리사의 임베드 컴포넌트에서 제출합니다.

Disputes can be rehearsed end to end in test mode, including winning and losing one. See Testing · Disputes.분쟁은 승소와 패소를 포함해 테스트 모드에서 끝까지 연습할 수 있습니다. 테스트 · 분쟁 섹션을 참고해 주십시오.

Field필드 Type타입 Description설명
id string
object string

The literal string dispute.고정 문자열 dispute입니다.
status enum

The chargeback's state, in OutlinePay's vocabulary and translated from whichever processor reported it. The inquiry_* set is the card networks' early retrieval request, raised before a formal chargeback. The rest is the real lifecycle, terminating in won/lost, or refunded when the merchant refunds instead of contesting.지불 거절의 상태로, OutlinePay의 용어이며 어느 처리사가 보고했든 변환되어 있습니다. inquiry_* 계열은 정식 지불 거절 전에 제기되는 카드 네트워크의 사전 조회 요청이고, 나머지가 실제 라이프사이클입니다. won/lost로 끝나거나, 가맹점이 다투는 대신 환불하면 refunded가 됩니다.

One of다음 중 하나
mode enum

The world this object lives in, test (sandbox) or live. Matches your API key's prefix (olp_sk_test_ / olp_sk_live_).이 객체가 속한 환경으로, test(샌드박스) 또는 live입니다. API 키의 접두사(olp_sk_test_ / olp_sk_live_)와 일치합니다.

One of다음 중 하나
payment_id string
merchant_id string
processor string

The rail the disputed charge is on, e.g. stripe. Inherited from the payment.분쟁이 걸린 결제 건의 경로입니다. 예: stripe. 결제에서 물려받습니다.
reason enum

Why the cardholder disputed, in OutlinePay's vocabulary, translated from the processor's own reason codes. bank_error covers the several ways a bank can decline to move the money, and anything we cannot place maps to other.카드 소지자가 지불 거절을 제기한 사유로, 처리사의 사유 코드를 OutlinePay의 용어로 변환한 값입니다. bank_error는 은행이 자금 이동을 거절하는 여러 경우를 묶은 값이고, 분류할 수 없는 값은 other로 대응됩니다. nullable

Accepted values (10)허용 값 (10개)
amount integer

Disputed amount, minor units.분쟁 금액이며 최소 단위입니다.
fee integer

What the processor charged the merchant to handle this dispute, in minor units (Stripe bills a flat 15.00 USD). Charged whether the dispute is won or lost, so winning still leaves the merchant down this much. The payment's fees.total and merchant_net account for it.이 분쟁의 처리 대가로 처리사가 가맹점에 청구한 금액이며 최소 단위입니다(Stripe는 정액 15.00 USD). 승패와 무관하게 청구되므로, 승소해도 가맹점은 이 금액만큼 손해입니다. 결제의 fees.total과 merchant_net에 반영됩니다. nullable
amount_withheld integer

How much of the payment the processor is currently holding back over this dispute, in minor units. Equal to amount from the moment a dispute opens, and 0 once the merchant wins. While it is above zero the payment cannot be refunded.이 분쟁으로 처리사가 현재 보류 중인 결제 금액이며 최소 단위입니다. 분쟁이 열리는 순간부터 amount와 같고, 가맹점이 승소하면 0이 됩니다. 0보다 큰 동안에는 결제를 환불할 수 없습니다. nullable
evidence_due_at string

Deadline to submit evidence, ISO 8601 UTC.증빙 제출 기한이며 ISO 8601 UTC 형식입니다. nullable
created_at string
The Dispute objectDispute 객체 
{
  "id": "dp_7Hq2Rf9wKc1V",
  "object": "dispute",
  "status": "needs_response",
  "mode": "test",
  "payment_id": "pay_3Nk8Qh2Lmp7T",
  "merchant_id": "mrc_9f2c8bAaZ1kQ",
  "reason": "fraudulent",
  "amount": 10000,
  "fee": 1500,
  "amount_withheld": 10000,
  "evidence_due_at": "2026-08-04T23:59:59Z",
  "created_at": "2026-07-21T13:00:00Z"
}

GET /v1/disputes

List disputes분쟁 목록 조회

Your disputes, newest first. Usually empty: a dispute exists only when a cardholder has opened a chargeback. Filter by merchant_id, payment_id, status and creation time.귀사의 분쟁을 최신순으로 반환합니다. 카드 소지자가 지불 거절을 제기한 경우에만 분쟁이 존재하므로 보통은 비어 있습니다. merchant_id, payment_id, status, 생성 시각으로 필터링하실 수 있습니다.

Conventions규약 A dispute does not un-settle a payment분쟁은 결제 상태를 되돌리지 않습니다

Parameters파라미터

Parameter파라미터 In위치 Type타입 Description설명
merchant_id
optional 		query string

Only disputes against this merchant's payments.이 가맹점의 결제에 대한 분쟁만 반환합니다.
payment_id
optional 		query string

Only disputes against this payment.이 결제에 대한 분쟁만 반환합니다.
status
optional 		query enum

The chargeback's state, in OutlinePay's vocabulary and translated from whichever processor reported it. The inquiry_* set is the card networks' early retrieval request, raised before a formal chargeback. The rest is the real lifecycle, terminating in won/lost, or refunded when the merchant refunds instead of contesting.지불 거절의 상태로, OutlinePay의 용어이며 어느 처리사가 보고했든 변환되어 있습니다. inquiry_* 계열은 정식 지불 거절 전에 제기되는 카드 네트워크의 사전 조회 요청이고, 나머지가 실제 라이프사이클입니다. won/lost로 끝나거나, 가맹점이 다투는 대신 환불하면 refunded가 됩니다.

Only disputes in this state.이 상태의 분쟁만 반환합니다.

One of다음 중 하나
created_after
optional 		query string

Only records whose created_at is at or after this ISO 8601 timestamp or date. Inclusive.created_at이 이 ISO 8601 시각 또는 날짜 이후(같은 시각 포함)인 항목만 반환합니다.
created_before
optional 		query string

Only records whose created_at is before this ISO 8601 timestamp or date. Exclusive, so a month's created_before is the next month's created_after.created_at이 이 ISO 8601 시각 또는 날짜 이전인 항목만 반환합니다. 같은 시각은 제외되므로, 한 달의 created_before가 다음 달의 created_after가 됩니다.
limit
optional 		query integer

Page size, 1–100 (default 20).페이지 크기이며 1~100(기본값 20)입니다.
starting_after
optional 		query string

A resource id. Returns records after it (newest-first cursor).리소스 id이며, 그 이후의 레코드를 반환합니다(최신순 커서).

Example request요청 예시

<?php
$ch = curl_init("https://api.outlinepay.com/v1/disputes?merchant_id=mrc_9f2c8bAaZ1kQ&payment_id=pay_3Nk8Qh2Lmp7T&created_after=2026-08-01T00:00:00Z&created_before=2026-09-01T00:00:00Z&limit=20");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer olp_sk_test_YOUR_KEY",
    ],
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Response응답

Returns a page of Dispute objects: { "data": [...], "has_more": bool }.Dispute 객체의 목록 페이지를 반환합니다: { "data": [...], "has_more": bool }.

GET /v1/disputes/{id}

Retrieve a dispute분쟁 조회

A single dispute, including its evidence deadline. Read-only.증빙 제출 기한을 포함한 개별 분쟁입니다. 읽기 전용입니다.

Conventions규약 A dispute does not un-settle a payment분쟁은 결제 상태를 되돌리지 않습니다

Parameters파라미터

Parameter파라미터 In위치 Type타입 Description설명
id
required 		path string

The dispute id.분쟁 id입니다.

Example request요청 예시

<?php
$ch = curl_init("https://api.outlinepay.com/v1/disputes/dp_7Hq2Rf9wKc1V");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer olp_sk_test_YOUR_KEY",
    ],
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Response응답

Returns a Dispute.Dispute 객체를 반환합니다.

Response응답 · 200 
{
  "id": "dp_7Hq2Rf9wKc1V",
  "object": "dispute",
  "status": "needs_response",
  "mode": "test",
  "payment_id": "pay_3Nk8Qh2Lmp7T",
  "merchant_id": "mrc_9f2c8bAaZ1kQ",
  "reason": "fraudulent",
  "amount": 10000,
  "fee": 1500,
  "amount_withheld": 10000,
  "evidence_due_at": "2026-08-04T23:59:59Z",
  "created_at": "2026-07-21T13:00:00Z"
}

Object객체

The Event objectEvent 객체

The replayable log of everything OutlinePay has emitted for you.OutlinePay가 귀사에 발행한 모든 이벤트의 재생 가능한 기록입니다.

Field필드 Type타입 Description설명
id string
object string

The literal string event.고정 문자열 event입니다.
type enum

The outbound event catalog.발신 이벤트 목록입니다.

payment.updated is the only type that is not a change of state. It fires a moment after a payment's outcome, carrying the facts that can only be read off the charge: the processor's own fee, the method that settled, and the card behind a card payment. All are still null on the outcome event itself, so record net from payment.updated, not from payment.succeeded. The full rule is under "Fees arrive just after the outcome" in Conventions.payment.updated는 상태 변경이 아닌 유일한 타입입니다. 결제 결과 직후에 발송되며, 결제 건에서만 읽을 수 있는 사실들, 즉 처리사 자신의 수수료, 실제로 정산된 수단, 그리고 카드 결제의 경우 해당 카드 정보를 담습니다. 모두 결과 이벤트 시점에는 아직 null이므로, 순수령액은 payment.succeeded가 아니라 payment.updated 기준으로 기록하십시오. 전체 규칙은 Conventions의 "Fees arrive just after the outcome"에 있습니다.

Accepted values (14)허용 값 (14개)
mode enum

The world this object lives in, test (sandbox) or live. Matches your API key's prefix (olp_sk_test_ / olp_sk_live_).이 객체가 속한 환경으로, test(샌드박스) 또는 live입니다. API 키의 접두사(olp_sk_test_ / olp_sk_live_)와 일치합니다.

One of다음 중 하나
created_at string
data object

The resource payload captured when the event was emitted: a Payment for payment.* events, a Merchant for merchant.*, and so on. Its object field names which, so a generic handler can branch on the payload rather than parsing the event type.이벤트 발행 시점에 캡처된 리소스 페이로드입니다. payment.* 이벤트에는 Payment가, merchant.*에는 Merchant가 담기는 식입니다. 어느 것인지는 페이로드의 object 필드가 알려 주므로, 범용 핸들러는 이벤트 타입 문자열을 파싱하는 대신 페이로드로 분기할 수 있습니다.
The Event objectEvent 객체 
{
  "id": "evt_9sK4Tb3vLm8P",
  "object": "event",
  "type": "payment.succeeded",
  "mode": "test",
  "created_at": "2026-07-21T13:02:11Z",
  "data": {
    "id": "pay_3Nk8Qh2Lmp7T",
    "object": "payment",
    "status": "awaiting_payment",
    "mode": "test",
    "merchant_id": "mrc_9f2c8bAaZ1kQ",
    "amount": 10000,
    "currency": "usd",
    "description": "Order",
    "customer": {
      "email": "[email protected]"
    },
    "fees": {
      "processor": null,
      "outline": 50,
      "partner": 100,
      "dispute": 0,
      "invoice": null,
      "fraud_screening": null,
      "tax": {
        "invoice": null,
        "fraud_screening": null
      },
      "total": 150
    },
    "merchant_net": 9850,
    "amount_refunded": 0,
    "amount_disputed": 0,
    "amount_refundable": 10000,
    "refunds": [],
    "disputes": [],
    "processor": "stripe",
    "processor_payment_method": null,
    "processor_reference": null,
    "selected_payment_method": null,
    "card": null,
    "bank_verification": null,
    "payment_link_id": null,
    "checkout_url": "https://checkout.outlinepay.com/c/pay_3Nk8Qh2Lmp7T",
    "receipt_url": null,
    "invoice_url": null,
    "localized_pricing": {
      "enabled": false
    },
    "presentment": null,
    "expires_at": "2026-07-22T12:45:00Z",
    "processing_at": null,
    "succeeded_at": null,
    "funds_available_at": null,
    "failed_at": null,
    "expired_at": null,
    "failure_reason": null,
    "created_at": "2026-07-21T12:45:00Z"
  }
}

GET /v1/events

List events이벤트 목록 조회

Everything OutlinePay has emitted for you, newest first. Replay past events any time. Filter by type and creation time.OutlinePay가 귀사에 발행한 모든 이벤트를 최신순으로 반환합니다. 지난 이벤트를 언제든 다시 받으실 수 있습니다. type과 생성 시각으로 필터링하실 수 있습니다.

Conventions규약 Webhook delivery웹훅 전달

Parameters파라미터

Parameter파라미터 In위치 Type타입 Description설명
type
optional 		query enum

The outbound event catalog.발신 이벤트 목록입니다.

payment.updated is the only type that is not a change of state. It fires a moment after a payment's outcome, carrying the facts that can only be read off the charge: the processor's own fee, the method that settled, and the card behind a card payment. All are still null on the outcome event itself, so record net from payment.updated, not from payment.succeeded. The full rule is under "Fees arrive just after the outcome" in Conventions.payment.updated는 상태 변경이 아닌 유일한 타입입니다. 결제 결과 직후에 발송되며, 결제 건에서만 읽을 수 있는 사실들, 즉 처리사 자신의 수수료, 실제로 정산된 수단, 그리고 카드 결제의 경우 해당 카드 정보를 담습니다. 모두 결과 이벤트 시점에는 아직 null이므로, 순수령액은 payment.succeeded가 아니라 payment.updated 기준으로 기록하십시오. 전체 규칙은 Conventions의 "Fees arrive just after the outcome"에 있습니다.

Only events of this type.이 타입의 이벤트만 반환합니다.

Accepted values (14)허용 값 (14개)
created_after
optional 		query string

Only records whose created_at is at or after this ISO 8601 timestamp or date. Inclusive.created_at이 이 ISO 8601 시각 또는 날짜 이후(같은 시각 포함)인 항목만 반환합니다.
created_before
optional 		query string

Only records whose created_at is before this ISO 8601 timestamp or date. Exclusive, so a month's created_before is the next month's created_after.created_at이 이 ISO 8601 시각 또는 날짜 이전인 항목만 반환합니다. 같은 시각은 제외되므로, 한 달의 created_before가 다음 달의 created_after가 됩니다.
limit
optional 		query integer

Page size, 1–100 (default 20).페이지 크기이며 1~100(기본값 20)입니다.
starting_after
optional 		query string

A resource id. Returns records after it (newest-first cursor).리소스 id이며, 그 이후의 레코드를 반환합니다(최신순 커서).

Example request요청 예시

<?php
$ch = curl_init("https://api.outlinepay.com/v1/events?created_after=2026-08-01T00:00:00Z&created_before=2026-09-01T00:00:00Z&limit=20");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer olp_sk_test_YOUR_KEY",
    ],
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Response응답

Returns a page of Event objects: { "data": [...], "has_more": bool }.Event 객체의 목록 페이지를 반환합니다: { "data": [...], "has_more": bool }.

GET /v1/events/{id}

Retrieve an event이벤트 조회

A single event exactly as it was emitted, for replaying or verifying a delivery.발행된 그대로의 개별 이벤트이며, 재처리하거나 전달 건을 검증하실 때 사용하십시오.

Conventions규약 Webhook delivery웹훅 전달

Parameters파라미터

Parameter파라미터 In위치 Type타입 Description설명
id
required 		path string

The event id.이벤트 id입니다.

Example request요청 예시

<?php
$ch = curl_init("https://api.outlinepay.com/v1/events/evt_9sK4Tb3vLm8P");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer olp_sk_test_YOUR_KEY",
    ],
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Response응답

Returns a Event.Event 객체를 반환합니다.

Response응답 · 200 
{
  "id": "evt_9sK4Tb3vLm8P",
  "object": "event",
  "type": "payment.succeeded",
  "mode": "test",
  "created_at": "2026-07-21T13:02:11Z",
  "data": {
    "id": "pay_3Nk8Qh2Lmp7T",
    "object": "payment",
    "status": "awaiting_payment",
    "mode": "test",
    "merchant_id": "mrc_9f2c8bAaZ1kQ",
    "amount": 10000,
    "currency": "usd",
    "description": "Order",
    "customer": {
      "email": "[email protected]"
    },
    "fees": {
      "processor": null,
      "outline": 50,
      "partner": 100,
      "dispute": 0,
      "invoice": null,
      "fraud_screening": null,
      "tax": {
        "invoice": null,
        "fraud_screening": null
      },
      "total": 150
    },
    "merchant_net": 9850,
    "amount_refunded": 0,
    "amount_disputed": 0,
    "amount_refundable": 10000,
    "refunds": [],
    "disputes": [],
    "processor": "stripe",
    "processor_payment_method": null,
    "processor_reference": null,
    "selected_payment_method": null,
    "card": null,
    "bank_verification": null,
    "payment_link_id": null,
    "checkout_url": "https://checkout.outlinepay.com/c/pay_3Nk8Qh2Lmp7T",
    "receipt_url": null,
    "invoice_url": null,
    "localized_pricing": {
      "enabled": false
    },
    "presentment": null,
    "expires_at": "2026-07-22T12:45:00Z",
    "processing_at": null,
    "succeeded_at": null,
    "funds_available_at": null,
    "failed_at": null,
    "expired_at": null,
    "failure_reason": null,
    "created_at": "2026-07-21T12:45:00Z"
  }
}

Object객체

The WebhookEndpoint objectWebhookEndpoint 객체

Where OutlinePay delivers signed events. The signing secret is shown once, at creation.OutlinePay가 서명된 이벤트를 전달하는 곳입니다. 서명 시크릿은 생성 시 단 한 번만 표시됩니다.

Field필드 Type타입 Description설명
id string
object string

The literal string webhook_endpoint.고정 문자열 webhook_endpoint입니다.
url string
status enum

Always active today: a deleted endpoint leaves the API entirely rather than appearing as disabled.현재는 항상 active입니다. 삭제된 엔드포인트는 disabled로 표시되는 대신 API에서 완전히 사라집니다.

One of다음 중 하나
mode enum

The world this object lives in, test (sandbox) or live. Matches your API key's prefix (olp_sk_test_ / olp_sk_live_).이 객체가 속한 환경으로, test(샌드박스) 또는 live입니다. API 키의 접두사(olp_sk_test_ / olp_sk_live_)와 일치합니다.

One of다음 중 하나
secret string

Signing secret. Returned only on creation.서명 시크릿입니다. 생성 시에만 반환됩니다. nullable
created_at string
The WebhookEndpoint objectWebhookEndpoint 객체 
{
  "id": "we_2Bd7Nq4pRs9K",
  "object": "webhook_endpoint",
  "url": "https://pg.cookiepay.example/outlinepay/webhook",
  "status": "active",
  "mode": "test",
  "secret": "olp_whsec_YOUR_SIGNING_SECRET",
  "created_at": "2026-07-21T12:00:00Z"
}

POST /v1/webhook_endpoints

Create a webhook endpoint웹훅 엔드포인트 생성

Subscribes an HTTPS URL to your events. The response reveals the signing secret exactly once. Store it, and use it to verify the OutlinePay-Signature header on every delivery. Each mode allows up to 16 active endpoints. Past that, creation fails with invalid_request until you delete one.HTTPS URL을 이벤트 수신 대상으로 등록합니다. 응답에는 서명 시크릿이 단 한 번만 포함되므로 반드시 저장하시고, 모든 전달 건의 OutlinePay-Signature 헤더 검증에 사용하십시오. 모드당 활성 엔드포인트는 최대 16개입니다. 초과하면 생성이 invalid_request로 거부되며, 기존 엔드포인트를 삭제하시면 다시 생성할 수 있습니다.

Conventions규약 Webhook delivery웹훅 전달

Request body요청 본문

Field필드 Type타입 Description설명
url
required 		string

An HTTPS URL to receive events.이벤트를 수신할 HTTPS URL입니다.

Example request요청 예시

<?php
$ch = curl_init("https://api.outlinepay.com/v1/webhook_endpoints");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer olp_sk_test_YOUR_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "url" => "https://pg.cookiepay.example/outlinepay/webhook",
    ]),
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Response응답

Returns a WebhookEndpoint.WebhookEndpoint 객체를 반환합니다.

Response응답 · 200 
{
  "id": "we_2Bd7Nq4pRs9K",
  "object": "webhook_endpoint",
  "url": "https://pg.cookiepay.example/outlinepay/webhook",
  "status": "active",
  "mode": "test",
  "secret": "olp_whsec_YOUR_SIGNING_SECRET",
  "created_at": "2026-07-21T12:00:00Z"
}

GET /v1/webhook_endpoints

List webhook endpoints웹훅 엔드포인트 목록 조회

Your endpoints, newest first. The signing secret is never included here. Filter by creation time.귀사의 엔드포인트를 최신순으로 반환합니다. 서명 시크릿은 이곳에 포함되지 않습니다. 생성 시각으로 필터링하실 수 있습니다.

Parameters파라미터

Parameter파라미터 In위치 Type타입 Description설명
created_after
optional 		query string

Only records whose created_at is at or after this ISO 8601 timestamp or date. Inclusive.created_at이 이 ISO 8601 시각 또는 날짜 이후(같은 시각 포함)인 항목만 반환합니다.
created_before
optional 		query string

Only records whose created_at is before this ISO 8601 timestamp or date. Exclusive, so a month's created_before is the next month's created_after.created_at이 이 ISO 8601 시각 또는 날짜 이전인 항목만 반환합니다. 같은 시각은 제외되므로, 한 달의 created_before가 다음 달의 created_after가 됩니다.
limit
optional 		query integer

Page size, 1–100 (default 20).페이지 크기이며 1~100(기본값 20)입니다.
starting_after
optional 		query string

A resource id. Returns records after it (newest-first cursor).리소스 id이며, 그 이후의 레코드를 반환합니다(최신순 커서).

Example request요청 예시

<?php
$ch = curl_init("https://api.outlinepay.com/v1/webhook_endpoints?created_after=2026-08-01T00:00:00Z&created_before=2026-09-01T00:00:00Z&limit=20");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer olp_sk_test_YOUR_KEY",
    ],
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Response응답

Returns a page of WebhookEndpoint objects: { "data": [...], "has_more": bool }.WebhookEndpoint 객체의 목록 페이지를 반환합니다: { "data": [...], "has_more": bool }.

DELETE /v1/webhook_endpoints/{id}

Delete a webhook endpoint웹훅 엔드포인트 삭제

Deletes the endpoint. Deliveries stop immediately, it disappears from the list, its slot under the 16-endpoint cap frees up, and its id is gone: a repeat call answers 404. There is no undo. To start delivering to the same URL again, create a new endpoint, which will have a new signing secret.엔드포인트를 삭제합니다. 전달이 즉시 중단되고, 목록에서 사라지며, 16개 제한의 자리가 반환되고, 해당 id는 더 이상 유효하지 않습니다. 같은 id로 다시 호출하면 404로 응답합니다. 되돌릴 수 없습니다. 같은 URL로 다시 전달하시려면 새 엔드포인트를 생성해 주십시오. 새 서명 시크릿이 발급됩니다.

Parameters파라미터

Parameter파라미터 In위치 Type타입 Description설명
id
required 		path string

The webhook endpoint id.웹훅 엔드포인트 id입니다.

Example request요청 예시

<?php
$ch = curl_init("https://api.outlinepay.com/v1/webhook_endpoints/we_2Bd7Nq4pRs9K");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => "DELETE",
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer olp_sk_test_YOUR_KEY",
    ],
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response . PHP_EOL;

Response응답

Field필드 Type타입 Description설명
id string
object string

The type of the resource that was deleted.삭제된 리소스의 타입입니다.
deleted boolean

Always true.항상 true입니다.
Response응답 · 200 
{
  "id": "we_2Bd7Nq4pRs9K",
  "object": "webhook_endpoint",
  "deleted": true
}